## Architecture ### 分层结构（Go + Gin + GORM） ``` backend/ ├── routes/ # HTTP 路由定义（按模块拆分） ├── handlers/ # 请求解析 + 响应组装（薄层，不含业务） ├── services/ # 业务逻辑（事务、组合、校验） ├── models/ # GORM 数据模型 ├── database/ # Repository 层（SQL、查询） ├── middleware/ # 认证、CORS、日志、限流 ├── migrations/ # SQL 迁移文件 └── utils/ # 通用工具（密码、签名等） ``` ### 分层规则（强制） 1. **请求流向**：Route → Handler → Service → Database → Models 2. **Handler 禁止直接访问 database**：必须走 Service 层 3. **Service 禁止调用 Handler 或 Route**：单向依赖 4. **Model 仅定义结构 + GORM tag**：不含业务方法 ### 命名规范 | 类型 | 约定 | 示例 | |------|------|------| | 文件名 | snake_case | `user_service.go` | | 包名 | lowercase | `services`, `handlers` | | 导出函数/类型 | PascalCase | `CreateUser`, `UserRepository` | | 内部函数 | camelCase | `validatePassword` | | 常量 | SCREAMING_SNAKE_CASE | `MAX_RETRY_COUNT` | ### 错误处理 - 使用 `errors.New()` 或自定义 error type - Handler 层统一返回 `{"code": X, "msg": "...", "data": ...}` - Service 层返回原始 error，由 Handler 转换 ### 日志 - 使用结构化 log：`log.WithField("user_id", uid).Info("...")` - 禁用 `fmt.Println` / `print` ### 测试 - 单元测试文件名：`xxx_test.go` - 使用 `testify/assert` - Mock 用 `testify/mock` 或 `gomock` ### 依赖检查 - **新 handler 禁止直接 `import database/`**：需走 Service 层 - `./scripts/check-architecture.sh check` 作为 CI 门禁