csxj2026/junhong_cmp_fiber

Files

huang d66323487b refactor: align framework cleanup with new bootstrap flow

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

2025-11-19 12:47:25 +08:00

7.0 KiB

Raw Permalink Blame History

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 和 Go Code Review Comments
变量命名使用 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）