187 lines
5.8 KiB
Markdown
187 lines
5.8 KiB
Markdown
|
# 项目目录结构规范
|
|||
|
|
|
|||
|
|
## 目录结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
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/` |
|