huang
d66323487b
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
201 lines
7.0 KiB
Markdown
201 lines
7.0 KiB
Markdown
# Project Context
|
||
|
||
## Purpose
|
||
|
||
junhong_cmp_fiber 是一个基于 Go + Fiber 的企业级中后台管理系统（Content Management Platform），提供完整的业务管理和数据处理能力。
|
||
|
||
**核心目标：**
|
||
- 提供高性能、可扩展的后端 API 服务
|
||
- 实现完善的权限管理和数据权限控制（RBAC）
|
||
- 支持异步任务处理和批量数据操作
|
||
- 提供统一的错误处理和日志审计能力
|
||
- 构建可维护、高质量的 Go 代码库
|
||
|
||
## Tech Stack
|
||
|
||
**核心框架：**
|
||
- **Go 1.25.4** - 编程语言
|
||
- **Fiber v2.x** - 高性能 HTTP 框架（基于 fasthttp）
|
||
- **GORM v1.25.x** - ORM 框架，用于数据库操作
|
||
|
||
**数据存储：**
|
||
- **PostgreSQL 14+** - 主数据库
|
||
- **Redis 6.0+** - 缓存和任务队列存储
|
||
|
||
**基础设施：**
|
||
- **Asynq v0.24.x** - 异步任务队列
|
||
- **Viper** - 配置管理
|
||
- **Zap + Lumberjack.v2** - 结构化日志和日志轮转
|
||
- **sonic** - 高性能 JSON 序列化
|
||
- **golang-migrate** - 数据库迁移工具
|
||
- **validator** - 请求参数验证
|
||
|
||
**开发工具：**
|
||
- **Go Modules** - 依赖管理
|
||
- **gofmt** - 代码格式化
|
||
- **go vet** - 静态分析
|
||
- **golangci-lint** - 代码质量检查
|
||
|
||
## Project Conventions
|
||
|
||
### Code Style
|
||
|
||
**严格遵循 Go 官方规范：**
|
||
- 必须使用 `gofmt` 格式化所有代码
|
||
- 遵循 [Effective Go](https://go.dev/doc/effective_go) 和 [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments)
|
||
- 变量命名使用 Go 风格：`userID`（不是 `userId`）、`HTTPServer`（不是 `HttpServer`）
|
||
- 缩写词全部大写或全部小写：`URL`、`ID`、`HTTP`（导出）或 `url`、`id`、`http`（未导出）
|
||
- 包名简短、小写、单数、无下划线：`user`、`order`、`pkg`
|
||
- 接口命名使用 `-er` 后缀：`Reader`、`Writer`、`Logger`
|
||
|
||
**注释和文档规范：**
|
||
- 所有导出的函数、类型和常量必须有 Go 风格文档注释（英文）
|
||
- 代码注释（implementation comments）使用中文
|
||
- 日志消息使用中文
|
||
- 用户可见错误消息使用中文（通过 `pkg/errors/` 双语支持）
|
||
- 变量名、函数名、类型名必须使用英文
|
||
|
||
**常量管理：**
|
||
- 业务常量必须定义在 `pkg/constants/`
|
||
- Redis key 必须使用函数生成：`Redis{Module}{Purpose}Key(params...)`
|
||
- Redis key 格式：`{module}:{purpose}:{identifier}`
|
||
- 禁止硬编码 magic numbers 和字符串字面量
|
||
|
||
**函数复杂度：**
|
||
- 函数长度不超过 50-100 行（核心逻辑 ≤ 50 行）
|
||
- 超过 100 行的函数必须拆分
|
||
- 遵循单一职责原则（Single Responsibility Principle）
|
||
|
||
### Architecture Patterns
|
||
|
||
**严格的四层架构：**
|
||
|
||
```
|
||
Handler 层 → Service 层 → Store 层 → Model 层
|
||
```
|
||
|
||
- **Handler 层**：处理 HTTP 请求/响应，参数验证，不包含业务逻辑
|
||
- **Service 层**：包含所有业务逻辑，支持跨模块调用
|
||
- **Store 层**：统一管理数据访问，支持事务处理
|
||
- **Model 层**：定义数据结构和 DTO
|
||
|
||
**依赖注入：**
|
||
- 所有依赖通过结构体字段注入（不使用构造函数模式）
|
||
- 禁止使用 Java 风格的 DI 框架
|
||
|
||
**错误处理：**
|
||
- 所有公共错误在 `pkg/errors/` 定义
|
||
- 使用统一错误码和双语错误消息
|
||
- Handler 层通过返回 `error` 传递给全局 ErrorHandler
|
||
- 禁止手动构造错误响应
|
||
|
||
**响应格式：**
|
||
- 所有 API 响应使用 `pkg/response/` 的统一格式
|
||
- 标准响应结构：`{code, message, data, timestamp}`
|
||
|
||
**数据库设计原则（核心）：**
|
||
- ❌ **禁止使用外键约束**（Foreign Key Constraints）
|
||
- ❌ **禁止使用 GORM 关联关系**（`foreignKey`、`hasMany`、`belongsTo` 等）
|
||
- ✅ 表之间关联通过存储关联 ID 字段手动维护
|
||
- ✅ 关联数据查询在代码层面显式执行
|
||
- ✅ 模型结构体只包含简单字段，不嵌套其他模型
|
||
- **理由**：灵活性、性能、可控性、分布式友好
|
||
|
||
**Go 惯用模式（vs Java）：**
|
||
- ✅ 扁平化包结构（按功能组织，不按层次）
|
||
- ✅ 小而专注的接口（1-3 个方法）
|
||
- ✅ 使用组合（composition），不是继承
|
||
- ✅ 直接访问导出字段，不使用 getter/setter
|
||
- ✅ 显式错误返回，不使用 panic/recover
|
||
- ❌ 禁止过度抽象（不必要的工厂、构造器）
|
||
- ❌ 禁止类型前缀（`IService`、`AbstractBase`、`ServiceImpl`）
|
||
|
||
### Testing Strategy
|
||
|
||
**测试要求：**
|
||
- 所有核心业务逻辑（Service 层）必须有单元测试
|
||
- 所有 API 端点必须有集成测试
|
||
- 测试使用 Go 标准 `testing` 包
|
||
- 测试文件命名：`*_test.go`
|
||
- 测试函数命名：`func TestUserCreate(t *testing.T)`
|
||
|
||
**测试性能：**
|
||
- 单元测试 < 100ms
|
||
- 集成测试 < 1s
|
||
- 测试覆盖率 ≥ 70%（核心业务 ≥ 90%）
|
||
|
||
**测试最佳实践：**
|
||
- 使用 table-driven tests 处理多个测试用例
|
||
- 使用 `t.Helper()` 标记辅助函数
|
||
- 使用 mock 或 testcontainers，不依赖外部服务
|
||
|
||
### Git Workflow
|
||
|
||
**分支策略：**
|
||
- 功能开发使用独立分支：`{feature-id}-{feature-name}`
|
||
- 完成后合并到主分支
|
||
|
||
**Commit 规范：**
|
||
- 遵循项目现有 commit message 风格
|
||
- 清晰描述变更内容和原因
|
||
- 包含 feature ID（如 `feat: 实现 RBAC 权限系统 (004-rbac-data-permission)`）
|
||
|
||
## Domain Context
|
||
|
||
**业务模块：**
|
||
- **RBAC 权限系统**：基于角色的访问控制，支持数据权限
|
||
- **用户管理**：用户注册、认证、权限分配
|
||
- **数据权限**：支持全部数据、本部门数据、本人数据、自定义数据权限
|
||
- **异步任务**：批量数据处理、定时任务
|
||
|
||
**核心概念：**
|
||
- **权限控制**：通过中间件实现路由级和数据级权限控制
|
||
- **数据隔离**：基于用户权限自动过滤查询数据
|
||
- **审计日志**：完整记录所有 API 请求和响应（request/response body）
|
||
|
||
## Important Constraints
|
||
|
||
**技术栈约束（严格遵守）：**
|
||
- ❌ 禁止使用 `database/sql` 直接调用（必须使用 GORM）
|
||
- ❌ 禁止使用 `net/http` 替代 Fiber
|
||
- ❌ 禁止使用 `encoding/json` 替代 sonic（除非必要）
|
||
- ❌ 禁止绕过框架使用原生调用
|
||
- **理由**：确保代码一致性、可维护性和长期技术债务可控
|
||
|
||
**性能要求：**
|
||
- API 响应时间（P95）< 200ms
|
||
- API 响应时间（P99）< 500ms
|
||
- 数据库查询 < 50ms
|
||
- 列表查询必须分页（默认 20，最大 100）
|
||
|
||
**资源限制：**
|
||
- API 服务内存 < 500MB
|
||
- Worker 服务内存 < 1GB
|
||
- 数据库连接池：MaxOpenConns=25, MaxIdleConns=10
|
||
- Redis 连接池：PoolSize=10, MinIdleConns=5
|
||
|
||
**安全要求：**
|
||
- 避免 OWASP Top 10 漏洞（XSS、SQL 注入、命令注入等）
|
||
- 敏感数据脱敏
|
||
- 完整的访问日志审计
|
||
|
||
**日志要求：**
|
||
- 所有 HTTP 请求必须记录访问日志（`access.log`）
|
||
- 记录完整请求/响应 body（限制 50KB）
|
||
- 使用 JSON 格式便于分析
|
||
|
||
## External Dependencies
|
||
|
||
**数据库：**
|
||
- PostgreSQL 14+ （必需，端口 5432）
|
||
- Redis 6.0+（必需，端口 6379）
|
||
|
||
**开发工具：**
|
||
- golang-migrate CLI（数据库迁移）
|
||
- golangci-lint（代码质量）
|
||
|
||
**可选服务：**
|
||
- 监控系统（Prometheus/Grafana）
|
||
- 日志收集（ELK Stack）
|
||
- API 文档（Swagger/OpenAPI）
|