long-agent
6b2b450e91
新增: - docs/PROJECT_STRUCTURE.md - 完整目录结构规范 - data/.gitkeep, logs/.gitkeep, testdata/.gitkeep, uploads/avatars/.gitkeep 更新: - .gitignore 添加临时文件规则 (*_result.txt, *_test*.txt 等) - .gitignore 添加 uploads/avatars/ 内容忽略规则
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/` |
|