From 6b2b450e917d430115792dc26232ca0203baae8b Mon Sep 17 00:00:00 2001 From: long-agent Date: Tue, 7 Apr 2026 19:00:51 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E7=BB=93=E6=9E=84=E8=A7=84=E8=8C=83=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增: - docs/PROJECT_STRUCTURE.md - 完整目录结构规范 - data/.gitkeep, logs/.gitkeep, testdata/.gitkeep, uploads/avatars/.gitkeep 更新: - .gitignore 添加临时文件规则 (*_result.txt, *_test*.txt 等) - .gitignore 添加 uploads/avatars/ 内容忽略规则 --- .gitignore | 15 +++ data/.gitkeep | 0 docs/PROJECT_STRUCTURE.md | 186 ++++++++++++++++++++++++++++++++++++++ logs/.gitkeep | 0 testdata/.gitkeep | 0 uploads/avatars/.gitkeep | 0 6 files changed, 201 insertions(+) create mode 100644 data/.gitkeep create mode 100644 docs/PROJECT_STRUCTURE.md create mode 100644 logs/.gitkeep create mode 100644 testdata/.gitkeep create mode 100644 uploads/avatars/.gitkeep diff --git a/.gitignore b/.gitignore index 51e86bc..3dd5b55 100644 --- a/.gitignore +++ b/.gitignore @@ -60,3 +60,18 @@ node_modules/ # NPM cache frontend/admin/.npm-cache/ + +# Temporary output files +*_result.txt +*_test*.txt +*_output.txt +*_err.txt +*.tmp +*.temp + +# Uploads (keep directory but ignore contents) +uploads/avatars/* +!uploads/avatars/.gitkeep + +# Backup temp +backup_temp/ diff --git a/data/.gitkeep b/data/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/PROJECT_STRUCTURE.md b/docs/PROJECT_STRUCTURE.md new file mode 100644 index 0000000..9061b89 --- /dev/null +++ b/docs/PROJECT_STRUCTURE.md @@ -0,0 +1,186 @@ +# 项目目录结构规范 + +## 目录结构 + +``` +project-root/ +├── .env.example # 环境变量示例（必须） +├── .gitignore # Git忽略规则（必须） +├── Makefile # 项目构建入口 +├── README.md # 项目说明 +├── go.mod / go.sum # Go模块定义 +├── go.work # Go workspace（多模块时） +│ +├── bin/ # 编译产物（二进制、可执行文件） +│ └── *.exe / main # 禁止提交编译产物 +│ +├── cmd/ # 应用入口（每个应用一个子目录） +│ └── server/ # 主服务器入口 +│ └── main.go +│ +├── internal/ # 私有内部包（不可被外部导入） +│ ├── api/ # API层 +│ │ ├── handler/ # HTTP Handler +│ │ ├── middleware/ # 中间件 +│ │ └── router/ # 路由 +│ ├── auth/ # 认证鉴权 +│ ├── cache/ # 缓存 +│ ├── config/ # 配置 +│ ├── database/ # 数据库 +│ ├── domain/ # 领域模型（实体、值对象） +│ ├── repository/ # 数据访问层 +│ ├── service/ # 业务逻辑层 +│ └── pkg/ # 内部共享工具包 +│ ├── errors/ # 错误定义 +│ ├── response/ # 响应封装 +│ └── ... +│ +├── pkg/ # 公共外部包（可被外部导入） +│ └── ... # 仅当需要作为独立库发布时使用 +│ +├── configs/ # 配置文件（JSON/YAML/TOML） +├── deployment/ # 部署配置（Docker/K8s/Compose） +│ ├── docker-compose.yml +│ ├── kubernetes/ +│ └── helm/ +│ +├── docs/ # 项目文档 +│ ├── guides/ # 使用指南 +│ ├── design/ # 设计文档 +│ ├── code-review/ # 代码审查报告 +│ └── specs/ # 规格说明 +│ +├── frontend/ # 前端代码 +│ └── admin/ # 管理后台前端 +│ +├── scripts/ # 脚本（按功能分类） +│ ├── dev/ # 开发脚本 +│ │ ├── run_tests.sh +│ │ └── check_gitea.sh +│ ├── deploy/ # 部署脚本 +│ │ └── deploy_*.sh +│ ├── ops/ # 运维脚本 +│ │ └── sre-*.ps1 +│ ├── test/ # 测试脚本 +│ │ └── test_*.sh +│ └── chaos/ # 混沌工程脚本 +│ +├── tools/ # 工具脚本（Python/Shell） +│ ├── db_check.go +│ └── *.py +│ +├── data/ # 运行时数据目录 +│ └── *.db # SQLite数据库文件 +│ +├── logs/ # 日志输出目录 +│ └── *.log +│ +├── migrations/ # 数据库迁移 +│ +├── testdata/ # 测试数据 +│ +├── uploads/ # 用户上传文件 +│ └── avatars/ # 头像上传 +│ +└── runtime/ # 运行时文件（pid/socket） +``` + +## 命名规范 + +### 目录命名 +- 使用 **小写字母 + 中划线** 或 **小写字母**（无特殊字符） +- 示例：`code-review`, `test-data`, `scripts` + +### 文件命名 +| 类型 | 规范 | 示例 | +|------|------|------| +| Go源文件 | `snake_case.go` | `user_service.go` | +| 测试文件 | `*_test.go` | `user_service_test.go` | +| 配置文件 | `snake_case.json/yaml/toml` | `database_config.yaml` | +| 脚本文件 | `snake_case.sh/ps1/py` | `check_gitea.sh` | +| Markdown | `snake_case.md` 或 ` kebab-case.md` | `api_design.md` | + +## 文件放置规则 + +### 禁止在根目录放置的文件 +- ❌ `*.exe`, `*.dll`, `*.so` （编译产物 → `bin/`） +- ❌ `*_result.txt`, `*_test.txt`, `*_output.log` （临时输出 → 删除） +- ❌ `*.tmp`, `*.log` （运行时文件 → 对应目录） +- ❌ `server.exe`, `ums.exe` （可执行文件 → `bin/`） +- ❌ `upload.json`, `debug.log` （临时文件 → 删除） + +### 必须放置根目录的文件 +- ✅ `go.mod`, `go.sum` （Go项目标识） +- ✅ `.gitignore` （Git配置） +- ✅ `.env.example` （环境变量模板） + +### 脚本放置规则 +| 脚本类型 | 放置位置 | +|----------|----------| +| 开发辅助 | `scripts/dev/` | +| 部署相关 | `scripts/deploy/` | +| 运维监控 | `scripts/ops/` | +| 测试相关 | `scripts/test/` | +| 混沌工程 | `scripts/chaos/` | + +## .gitignore 规范 + +```gitignore +# 编译产物 +bin/ +*.exe +*.dll +*.so + +# 运行时数据 +*.db +*.log +logs/ +data/*.db + +# 上传文件 +uploads/avatars/* +!uploads/avatars/.gitkeep + +# 临时文件 +*.tmp +*.temp +*_result.txt +*_test*.txt +*_output.txt + +# 环境配置 +.env +.env.local + +# IDE +.idea/ +.vscode/ +*.swp + +# 系统文件 +.DS_Store +Thumbs.db + +# Go +.gocache/ +.gomodcache/ +``` + +## 新增目录检查清单 + +添加新目录前，确认： + +1. **是否有必要？** 能用现有目录表达吗？ +2. **符合命名规范？** 小写字母、中划线分隔 +3. **放置位置正确？** 对应到上表的位置 +4. **是否需要版本控制？** `data/`、`logs/`、`uploads/` 通常不提交 + +## 常见错误 + +| 错误 | 正确做法 | +|------|----------| +| 在根目录放置 `test_output.txt` | 删除或放到 `scripts/test/` | +| 在根目录放置 `server.exe` | 移动到 `bin/` | +| 创建 `internal/utils/` | 使用现有 `internal/pkg/` | +| 创建 `pkg/response/` | 使用 `internal/pkg/response/` | diff --git a/logs/.gitkeep b/logs/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/testdata/.gitkeep b/testdata/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/uploads/avatars/.gitkeep b/uploads/avatars/.gitkeep new file mode 100644 index 0000000..e69de29