diff --git a/.claude/commands/openspec/apply.md b/.claude/commands/openspec/apply.md new file mode 100644 index 0000000..a36fd96 --- /dev/null +++ b/.claude/commands/openspec/apply.md @@ -0,0 +1,23 @@ +--- +name: OpenSpec: Apply +description: Implement an approved OpenSpec change and keep tasks in sync. +category: OpenSpec +tags: [openspec, apply] +--- + +**Guardrails** +- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required. +- Keep changes tightly scoped to the requested outcome. +- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications. + +**Steps** +Track these steps as TODOs and complete them one by one. +1. Read `changes//proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria. +2. Work through tasks sequentially, keeping edits minimal and focused on the requested change. +3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished. +4. Update the checklist after all work is done so each task is marked `- [x]` and reflects reality. +5. Reference `openspec list` or `openspec show ` when additional context is required. + +**Reference** +- Use `openspec show --json --deltas-only` if you need additional context from the proposal while implementing. + diff --git a/.claude/commands/openspec/archive.md b/.claude/commands/openspec/archive.md new file mode 100644 index 0000000..dbc7695 --- /dev/null +++ b/.claude/commands/openspec/archive.md @@ -0,0 +1,27 @@ +--- +name: OpenSpec: Archive +description: Archive a deployed OpenSpec change and update specs. +category: OpenSpec +tags: [openspec, archive] +--- + +**Guardrails** +- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required. +- Keep changes tightly scoped to the requested outcome. +- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications. + +**Steps** +1. Determine the change ID to archive: + - If this prompt already includes a specific change ID (for example inside a `` block populated by slash-command arguments), use that value after trimming whitespace. + - If the conversation references a change loosely (for example by title or summary), run `openspec list` to surface likely IDs, share the relevant candidates, and confirm which one the user intends. + - Otherwise, review the conversation, run `openspec list`, and ask the user which change to archive; wait for a confirmed change ID before proceeding. + - If you still cannot identify a single change ID, stop and tell the user you cannot archive anything yet. +2. Validate the change ID by running `openspec list` (or `openspec show `) and stop if the change is missing, already archived, or otherwise not ready to archive. +3. Run `openspec archive --yes` so the CLI moves the change and applies spec updates without prompts (use `--skip-specs` only for tooling-only work). +4. Review the command output to confirm the target specs were updated and the change landed in `changes/archive/`. +5. Validate with `openspec validate --strict` and inspect with `openspec show ` if anything looks off. + +**Reference** +- Use `openspec list` to confirm change IDs before archiving. +- Inspect refreshed specs with `openspec list --specs` and address any validation issues before handing off. + diff --git a/.claude/commands/openspec/proposal.md b/.claude/commands/openspec/proposal.md new file mode 100644 index 0000000..f4c1c97 --- /dev/null +++ b/.claude/commands/openspec/proposal.md @@ -0,0 +1,27 @@ +--- +name: OpenSpec: Proposal +description: Scaffold a new OpenSpec change and validate strictly. +category: OpenSpec +tags: [openspec, change] +--- + +**Guardrails** +- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required. +- Keep changes tightly scoped to the requested outcome. +- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications. +- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files. + +**Steps** +1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification. +2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes//`. +3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing. +4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs. +5. Draft spec deltas in `changes//specs//spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant. +6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work. +7. Validate with `openspec validate --strict` and resolve every issue before sharing the proposal. + +**Reference** +- Use `openspec show --json --deltas-only` or `openspec show --type spec` to inspect details when validation fails. +- Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones. +- Explore the codebase with `rg `, `ls`, or direct file reads so proposals align with current implementation realities. + diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 0000000..ae3244c --- /dev/null +++ b/.claude/settings.local.json @@ -0,0 +1,33 @@ +{ + "permissions": { + "allow": [ + "Bash(.specify/scripts/bash/check-prerequisites.sh:*)", + "Bash(.specify/scripts/bash/setup-plan.sh:*)", + "Bash(git rev-parse:*)", + "Bash(gofmt:*)", + "Bash(go vet:*)", + "Bash(find:*)", + "Bash(go mod:*)", + "Bash(go build:*)", + "Bash(go test ./pkg/... -v -short)", + "Bash(go test:*)", + "Bash(golangci-lint run:*)", + "Bash(if [ -d \"/Users/break/csxjProject/junhong_cmp_fiber/specs/004-rbac-data-permission/checklists\" ])", + "Bash(then echo \"EXISTS\")", + "Bash(else echo \"NO_CHECKLISTS\")", + "Bash(fi)", + "Bash(psql:*)", + "Bash(pg_isready:*)", + "Bash(staticcheck:*)", + "Bash(git fetch:*)", + "Bash(.specify/scripts/bash/create-new-feature.sh:*)", + "Bash(tree:*)", + "Bash(xargs ls:*)", + "Bash(mkdir:*)", + "WebFetch(domain:gorm.io)", + "Bash(openspec validate:*)" + ], + "deny": [], + "ask": [] + } +} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c8e79d4 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,170 @@ + +# OpenSpec Instructions + +These instructions are for AI assistants working in this project. + +Always open `@/openspec/AGENTS.md` when the request: +- Mentions planning or proposals (words like proposal, spec, change, plan) +- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work +- Sounds ambiguous and you need the authoritative spec before coding + +Use `@/openspec/AGENTS.md` to learn: +- How to create and apply change proposals +- Spec format and conventions +- Project structure and guidelines + +Keep this managed block so 'openspec update' can refresh the instructions. + + + +--- + +# junhong_cmp_fiber 项目开发规范 + +**重要提示**: 完整的开发规范和 OpenSpec 工作流详细说明请查看 `@/openspec/AGENTS.md` + +## 语言要求 + +**必须遵守:** +- 永远用中文交互 +- 注释必须使用中文 +- 文档必须使用中文 +- 日志消息必须使用中文 +- 用户可见的错误消息必须使用中文 +- 变量名、函数名、类型名必须使用英文（遵循 Go 命名规范） + +## 技术栈 + +**必须严格遵守以下技术栈，禁止使用替代方案:** + +- **HTTP 框架**: Fiber v2.x +- **ORM**: GORM v1.25.x +- **配置管理**: Viper +- **日志**: Zap + Lumberjack.v2 +- **JSON 序列化**: sonic（优先），encoding/json（必要时） +- **验证**: Validator +- **任务队列**: Asynq v0.24.x +- **数据库**: PostgreSQL 14+ +- **缓存**: Redis 6.0+ + +**禁止:** +- 直接使用 `database/sql`（必须通过 GORM） +- 使用 `net/http` 替代 Fiber +- 使用 `encoding/json` 替代 sonic（除非必要） + +## 架构分层 + +必须遵循以下分层架构： + +``` +Handler → Service → Store → Model +``` + +- **Handler**: 只处理 HTTP 请求/响应，不包含业务逻辑 +- **Service**: 包含所有业务逻辑，支持跨模块调用 +- **Store**: 统一管理所有数据访问，支持事务处理 +- **Model**: 定义数据结构和 DTO + +## 核心原则 + +### 错误处理 +- 所有错误必须在 `pkg/errors/` 中定义 +- 使用统一错误码系统 +- Handler 层通过返回 `error` 传递给全局 ErrorHandler + +### 响应格式 +- 所有 API 响应使用 `pkg/response/` 的统一格式 +- 格式: `{code, message, data, timestamp}` + +### 常量管理 +- 所有常量定义在 `pkg/constants/` +- Redis key 使用函数生成: `Redis{Module}{Purpose}Key(params...)` +- 格式: `{module}:{purpose}:{identifier}` +- 禁止硬编码字符串和 magic numbers + +### Go 代码风格 +- 使用 `gofmt` 格式化 +- 遵循 [Effective Go](https://go.dev/doc/effective_go) +- 包名: 简短、小写、单数、无下划线 +- 接口命名: 使用 `-er` 后缀（Reader、Writer、Logger） +- 缩写词: 全大写或全小写（URL、ID、HTTP 或 url、id、http） + +## 数据库设计 + +**核心规则:** +- ❌ 禁止建立外键约束 +- ❌ 禁止使用 GORM 关联关系标签（foreignKey、hasMany、belongsTo） +- ✅ 关联通过存储 ID 字段手动维护 +- ✅ 关联数据在代码层面显式查询 + +**理由**: 灵活性、性能、可控性、分布式友好 + +## Go 惯用法 vs Java 风格 + +### ✅ Go 风格（推荐） +- 扁平化包结构（最多 2-3 层） +- 小而专注的接口（1-3 个方法） +- 直接访问导出字段（不用 getter/setter） +- 组合优于继承 +- 显式错误返回和检查 +- goroutines + channels（不用线程池） + +### ❌ Java 风格（禁止） +- 过度抽象（不必要的接口、工厂） +- Getter/Setter 方法 +- 深层继承层次 +- 异常处理（panic/recover） +- 单例模式 +- 类型前缀（IService、AbstractBase、ServiceImpl） +- Bean 风格 + +## 测试要求 + +- 核心业务逻辑（Service 层）测试覆盖率 ≥ 90% +- 所有 API 端点必须有集成测试 +- 使用 table-driven tests +- 单元测试 < 100ms，集成测试 < 1s + +## 性能要求 + +- API P95 响应时间 < 200ms +- API P99 响应时间 < 500ms +- 数据库查询 < 50ms +- 列表查询必须分页（默认 20，最大 100） +- 避免 N+1 查询，使用批量操作 + +## 文档要求 + +- 每个功能在 `docs/{feature-id}/` 创建总结文档 +- 文档文件名和内容使用中文 +- 同步更新 README.md +- 为导出的函数、类型编写文档注释 + +## 函数复杂度 + +- 函数长度 ≤ 100 行（核心逻辑建议 ≤ 50 行） +- `main()` 函数只做编排，不含具体实现 +- 遵循单一职责原则 + +## 访问日志 + +- 所有 HTTP 请求记录到 `access.log` +- 记录完整的请求/响应（限制 50KB） +- 包含: method, path, query, status, duration, request_id, ip, user_agent, user_id, bodies +- 使用 JSON 格式，配置自动轮转 + +## OpenSpec 工作流 + +创建提案前的检查清单： + +1. ✅ 技术栈合规 +2. ✅ 架构分层正确 +3. ✅ 使用统一错误处理 +4. ✅ 常量定义在 pkg/constants/ +5. ✅ Go 惯用法（非 Java 风格） +6. ✅ 包含测试计划 +7. ✅ 性能考虑 +8. ✅ 文档更新计划 +9. ✅ 中文优先 + +**详细规范和 OpenSpec 工作流请查看**: `@/openspec/AGENTS.md` \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 94efe2d..49aeab4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,3 +1,22 @@ + +# OpenSpec Instructions + +These instructions are for AI assistants working in this project. + +Always open `@/openspec/AGENTS.md` when the request: +- Mentions planning or proposals (words like proposal, spec, change, plan) +- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work +- Sounds ambiguous and you need the authoritative spec before coding + +Use `@/openspec/AGENTS.md` to learn: +- How to create and apply change proposals +- Spec format and conventions +- Project structure and guidelines + +Keep this managed block so 'openspec update' can refresh the instructions. + + + # junhong_cmp_fiber Development Guidelines Auto-generated from all feature plans. Last updated: 2025-11-10 @@ -9,6 +28,7 @@ Auto-generated from all feature plans. Last updated: 2025-11-10 - PostgreSQL 14+ (主数据库), Redis 6.0+ (缓存和任务队列) (004-rbac-data-permission) - Go 1.25.4 + Fiber v2.x (HTTP 框架), GORM v1.25.x (ORM), Viper (配置管理), Zap + Lumberjack.v2 (日志), sonic (JSON 序列化), Asynq v0.24.x (异步任务队列), golang-migrate (数据库迁移) (004-rbac-data-permission) - PostgreSQL 14+ (主数据库), Redis 6.0+ (缓存和任务队列存储) (004-rbac-data-permission) +- Go 1.25.4 + Fiber v2.x (HTTP), GORM v1.25.x (ORM), Asynq v0.24.x (任务队列), Viper (配置), Zap + Lumberjack.v2 (日志), sonic (JSON), Validator (005-framework-cleanup-refactor) - Go 1.25.4 (001-fiber-middleware-integration) @@ -385,10 +405,11 @@ docs/001-fiber-middleware-integration/ # 功能总结文档（完成阶段） --- ## Recent Changes +- 005-framework-cleanup-refactor: Added Go 1.25.4 + Fiber v2.x (HTTP), GORM v1.25.x (ORM), Asynq v0.24.x (任务队列), Viper (配置), Zap + Lumberjack.v2 (日志), sonic (JSON), Validator - 004-rbac-data-permission: Added Go 1.25.4 + Fiber v2.x (HTTP 框架), GORM v1.25.x (ORM), Viper (配置管理), Zap + Lumberjack.v2 (日志), sonic (JSON 序列化), Asynq v0.24.x (异步任务队列), golang-migrate (数据库迁移) - 004-rbac-data-permission: Added [if applicable, e.g., PostgreSQL, CoreData, files or N/A] -- 004-rbac-data-permission: Added Go 1.25.4 + Fiber (HTTP 框架), GORM (ORM), Asynq (任务队列), Viper (配置), Zap (日志), Redis, PostgreSQL +永远用中文交互,注释以及文档也要使用中文(必须) diff --git a/README.md b/README.md index 43ba4d4..f97815a 100644 --- a/README.md +++ b/README.md @@ -417,6 +417,36 @@ Handler (HTTP) → Service (业务逻辑) → Store (数据访问) → Model ( - **Store 层**：统一管理所有数据访问，支持事务 - **Task 层**：Asynq 任务处理器，支持定时任务和事件触发 +## 框架优化历史 + +### 005-framework-cleanup-refactor（2025-11） + +**背景**：清理技术债务，统一框架设计 + +**主要变更**： +1. **清理示例代码**：删除所有 user/order 示例业务代码，保持代码库整洁 +2. **统一认证中间件**：合并两套 Auth 实现到 `pkg/middleware/auth.go`，统一错误处理格式 +3. **简化错误结构**：删除 AppError 的 HTTPStatus 字段，避免字段冗余 +4. **组件注册解耦**：创建 `internal/bootstrap/` 包实现自动化组件初始化 + - 按模块拆分：`stores.go`、`services.go`、`handlers.go` + - main.go 简化为一行：`handlers, err := bootstrap.Bootstrap(deps)` +5. **数据权限自动化**：实现 GORM Callback 自动注入数据权限过滤 + - 基于 creator 字段自动过滤（普通用户只能看到自己和下级的数据） + - root 用户自动跳过过滤 + - 支持通过 `gorm.SkipDataPermission(ctx)` 手动绕过 + - 删除未使用的 `scopes.go` 手动 Scope 函数 + +**设计原则**： +- 保持 Go 惯用模式，避免 Java 风格过度抽象 +- 使用显式依赖注入，不引入复杂的 DI 框架 +- 每个文件保持 < 100 行，职责单一 +- 在关键扩展点添加 TODO 标记 + +**详细文档**： +- [变更提案](openspec/changes/refactor-framework-cleanup/proposal.md) +- [设计文档](openspec/changes/refactor-framework-cleanup/design.md) +- [任务清单](openspec/changes/refactor-framework-cleanup/tasks.md) + ## 开发规范 ### 依赖注入 diff --git a/cmd/api/main.go b/cmd/api/main.go index 5c3062a..dc3c9be 100644 --- a/cmd/api/main.go +++ b/cmd/api/main.go @@ -16,13 +16,9 @@ import ( "go.uber.org/zap" "gorm.io/gorm" - "github.com/break/junhong_cmp_fiber/internal/handler" + "github.com/break/junhong_cmp_fiber/internal/bootstrap" internalMiddleware "github.com/break/junhong_cmp_fiber/internal/middleware" "github.com/break/junhong_cmp_fiber/internal/routes" - accountSvc "github.com/break/junhong_cmp_fiber/internal/service/account" - permissionSvc "github.com/break/junhong_cmp_fiber/internal/service/permission" - roleSvc "github.com/break/junhong_cmp_fiber/internal/service/role" - "github.com/break/junhong_cmp_fiber/internal/store/postgres" "github.com/break/junhong_cmp_fiber/pkg/config" "github.com/break/junhong_cmp_fiber/pkg/database" "github.com/break/junhong_cmp_fiber/pkg/logger" @@ -51,8 +47,15 @@ func main() { queueClient := initQueue(redisClient, appLogger) defer closeQueue(queueClient, appLogger) - // 6. 初始化 Services - services := initServices(db, redisClient, appLogger) + // 6. 初始化所有业务组件（通过 Bootstrap） + handlers, err := bootstrap.Bootstrap(&bootstrap.Dependencies{ + DB: db, + Redis: redisClient, + Logger: appLogger, + }) + if err != nil { + appLogger.Fatal("初始化业务组件失败", zap.Error(err)) + } // 7. 启动配置监听器 watchCtx, cancelWatch := context.WithCancel(context.Background()) @@ -66,7 +69,7 @@ func main() { initMiddleware(app, cfg, appLogger) // 10. 注册路由 - initRoutes(app, cfg, services, queueClient, db, redisClient, appLogger) + initRoutes(app, cfg, handlers, queueClient, db, redisClient, appLogger) // 11. 启动服务器 startServer(app, cfg, appLogger, cancelWatch) @@ -131,8 +134,8 @@ func closeDatabase(db *gorm.DB, appLogger *zap.Logger) { // initRedis 初始化 Redis 连接 func initRedis(cfg *config.Config, appLogger *zap.Logger) *redis.Client { redisAddr := cfg.Redis.Address + ":" + strconv.Itoa(cfg.Redis.Port) - redisClient := redis.NewClient(&redis.Options{ - Addr: redisAddr, + redisClient, err := database.NewRedisClient(database.RedisConfig{ + Address: redisAddr, Password: cfg.Redis.Password, DB: cfg.Redis.DB, PoolSize: cfg.Redis.PoolSize, @@ -140,15 +143,11 @@ func initRedis(cfg *config.Config, appLogger *zap.Logger) *redis.Client { DialTimeout: cfg.Redis.DialTimeout, ReadTimeout: cfg.Redis.ReadTimeout, WriteTimeout: cfg.Redis.WriteTimeout, - }) + }, appLogger) - // 测试连接 - ctx := context.Background() - if err := redisClient.Ping(ctx).Err(); err != nil { + if err != nil { appLogger.Fatal("连接 Redis 失败", zap.Error(err)) } - appLogger.Info("Redis 已连接", zap.String("address", redisAddr)) - return redisClient } @@ -171,32 +170,6 @@ func closeQueue(queueClient *queue.Client, appLogger *zap.Logger) { } } -// initServices 初始化所有 Services -func initServices(db *gorm.DB, redisClient *redis.Client, appLogger *zap.Logger) *routes.Services { - // 初始化 RBAC Store 层 - accountStore := postgres.NewAccountStore(db, redisClient) - roleStore := postgres.NewRoleStore(db) - permissionStore := postgres.NewPermissionStore(db) - accountRoleStore := postgres.NewAccountRoleStore(db) - rolePermissionStore := postgres.NewRolePermissionStore(db) - - // 初始化 RBAC Service 层 - accountService := accountSvc.New(accountStore, roleStore, accountRoleStore) - roleService := roleSvc.New(roleStore, permissionStore, rolePermissionStore) - permissionService := permissionSvc.New(permissionStore) - - // 初始化 Handler 层 - accountHandler := handler.NewAccountHandler(accountService) - roleHandler := handler.NewRoleHandler(roleService) - permissionHandler := handler.NewPermissionHandler(permissionService) - - return &routes.Services{ - AccountHandler: accountHandler, - RoleHandler: roleHandler, - PermissionHandler: permissionHandler, - } -} - // createFiberApp 创建 Fiber 应用 func createFiberApp(cfg *config.Config, appLogger *zap.Logger) *fiber.App { return fiber.New(fiber.Config{ @@ -234,9 +207,9 @@ func initMiddleware(app *fiber.App, cfg *config.Config, appLogger *zap.Logger) { } // initRoutes 注册路由 -func initRoutes(app *fiber.App, cfg *config.Config, services *routes.Services, queueClient *queue.Client, db *gorm.DB, redisClient *redis.Client, appLogger *zap.Logger) { +func initRoutes(app *fiber.App, cfg *config.Config, handlers *bootstrap.Handlers, queueClient *queue.Client, db *gorm.DB, redisClient *redis.Client, appLogger *zap.Logger) { // 注册模块化路由 - routes.RegisterRoutes(app, services) + routes.RegisterRoutes(app, handlers) // API v1 路由组（用于受保护的端点） v1 := app.Group("/api/v1") diff --git a/configs/config.dev.yaml b/configs/config.dev.yaml index 3dd918d..549adc6 100644 --- a/configs/config.dev.yaml +++ b/configs/config.dev.yaml @@ -58,4 +58,4 @@ middleware: rate_limiter: max: 1000 expiration: "1m" - storage: "memory" + storage: "redis" diff --git a/go.mod b/go.mod index cf2f6f9..f266478 100644 --- a/go.mod +++ b/go.mod @@ -11,14 +11,13 @@ require ( github.com/golang-migrate/migrate/v4 v4.19.0 github.com/google/uuid v1.6.0 github.com/hibiken/asynq v0.25.1 - github.com/lib/pq v1.10.9 github.com/redis/go-redis/v9 v9.16.0 github.com/spf13/viper v1.21.0 github.com/stretchr/testify v1.11.1 github.com/testcontainers/testcontainers-go v0.40.0 github.com/testcontainers/testcontainers-go/modules/postgres v0.40.0 github.com/testcontainers/testcontainers-go/modules/redis v0.38.0 - github.com/valyala/fasthttp v1.51.0 + github.com/valyala/fasthttp v1.66.0 go.uber.org/zap v1.27.0 golang.org/x/crypto v0.44.0 gopkg.in/natefinch/lumberjack.v2 v2.2.1 @@ -31,7 +30,7 @@ require ( dario.cat/mergo v1.0.2 // indirect github.com/Azure/go-ansiterm v0.0.0-20230124172434-306776ec8161 // indirect github.com/Microsoft/go-winio v0.6.2 // indirect - github.com/andybalholm/brotli v1.1.0 // indirect + github.com/andybalholm/brotli v1.2.0 // indirect github.com/bytedance/gopkg v0.1.3 // indirect github.com/bytedance/sonic/loader v0.4.0 // indirect github.com/cenkalti/backoff/v4 v4.3.0 // indirect @@ -69,6 +68,7 @@ require ( github.com/klauspost/compress v1.18.0 // indirect github.com/klauspost/cpuid/v2 v2.2.9 // indirect github.com/leodido/go-urn v1.4.0 // indirect + github.com/lib/pq v1.10.9 // indirect github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect github.com/magiconair/properties v1.8.10 // indirect github.com/mattn/go-colorable v0.1.13 // indirect @@ -107,15 +107,14 @@ require ( github.com/tklauser/numcpus v0.6.1 // indirect github.com/twitchyliquid64/golang-asm v0.15.1 // indirect github.com/valyala/bytebufferpool v1.0.0 // indirect - github.com/valyala/tcplisten v1.0.0 // indirect github.com/yusufpapurcu/wmi v1.2.4 // indirect go.opentelemetry.io/auto/sdk v1.1.0 // indirect go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.54.0 // indirect - go.opentelemetry.io/otel v1.37.0 // indirect - go.opentelemetry.io/otel/metric v1.37.0 // indirect - go.opentelemetry.io/otel/sdk v1.37.0 // indirect - go.opentelemetry.io/otel/trace v1.37.0 // indirect - go.uber.org/multierr v1.10.0 // indirect + go.opentelemetry.io/otel v1.38.0 // indirect + go.opentelemetry.io/otel/metric v1.38.0 // indirect + go.opentelemetry.io/otel/sdk v1.38.0 // indirect + go.opentelemetry.io/otel/trace v1.38.0 // indirect + go.uber.org/multierr v1.11.0 // indirect go.yaml.in/yaml/v3 v3.0.4 // indirect golang.org/x/arch v0.0.0-20210923205945-b76863e36670 // indirect golang.org/x/sync v0.18.0 // indirect diff --git a/go.sum b/go.sum index 349df59..0cd5a77 100644 --- a/go.sum +++ b/go.sum @@ -6,8 +6,8 @@ github.com/Azure/go-ansiterm v0.0.0-20230124172434-306776ec8161 h1:L/gRVlceqvL25 github.com/Azure/go-ansiterm v0.0.0-20230124172434-306776ec8161/go.mod h1:xomTg63KZ2rFqZQzSB4Vz2SUXa1BpHTVz9L5PTmPC4E= github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY= github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU= -github.com/andybalholm/brotli v1.1.0 h1:eLKJA0d02Lf0mVpIDgYnqXcUn0GqVmEFny3VuID1U3M= -github.com/andybalholm/brotli v1.1.0/go.mod h1:sms7XGricyQI9K10gOSf56VKKWS4oLer58Q+mhRPtnY= +github.com/andybalholm/brotli v1.2.0 h1:ukwgCxwYrmACq68yiUqwIWnGY0cTPox/M94sVwToPjQ= +github.com/andybalholm/brotli v1.2.0/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY= github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs= github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c= github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA= @@ -226,34 +226,34 @@ github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08= github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw= github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc= -github.com/valyala/fasthttp v1.51.0 h1:8b30A5JlZ6C7AS81RsWjYMQmrZG6feChmgAolCl1SqA= -github.com/valyala/fasthttp v1.51.0/go.mod h1:oI2XroL+lI7vdXyYoQk03bXBThfFl2cVdIA3Xl7cH8g= -github.com/valyala/tcplisten v1.0.0 h1:rBHj/Xf+E1tRGZyWIWwJDiRY0zc1Js+CV5DqwacVSA8= -github.com/valyala/tcplisten v1.0.0/go.mod h1:T0xQ8SeCZGxckz9qRXTfG43PvQ/mcWh7FwZEA7Ioqkc= +github.com/valyala/fasthttp v1.66.0 h1:M87A0Z7EayeyNaV6pfO3tUTUiYO0dZfEJnRGXTVNuyU= +github.com/valyala/fasthttp v1.66.0/go.mod h1:Y4eC+zwoocmXSVCB1JmhNbYtS7tZPRI2ztPB72EVObs= +github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU= +github.com/xyproto/randomstring v1.0.5/go.mod h1:rgmS5DeNXLivK7YprL0pY+lTuhNQW3iGxZ18UQApw/E= github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo0= github.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0= go.opentelemetry.io/auto/sdk v1.1.0 h1:cH53jehLUN6UFLY71z+NDOiNJqDdPRaXzTel0sJySYA= go.opentelemetry.io/auto/sdk v1.1.0/go.mod h1:3wSPjt5PWp2RhlCcmmOial7AvC4DQqZb7a7wCow3W8A= go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.54.0 h1:TT4fX+nBOA/+LUkobKGW1ydGcn+G3vRw9+g5HwCphpk= go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.54.0/go.mod h1:L7UH0GbB0p47T4Rri3uHjbpCFYrVrwc1I25QhNPiGK8= -go.opentelemetry.io/otel v1.37.0 h1:9zhNfelUvx0KBfu/gb+ZgeAfAgtWrfHJZcAqFC228wQ= -go.opentelemetry.io/otel v1.37.0/go.mod h1:ehE/umFRLnuLa/vSccNq9oS1ErUlkkK71gMcN34UG8I= +go.opentelemetry.io/otel v1.38.0 h1:RkfdswUDRimDg0m2Az18RKOsnI8UDzppJAtj01/Ymk8= +go.opentelemetry.io/otel v1.38.0/go.mod h1:zcmtmQ1+YmQM9wrNsTGV/q/uyusom3P8RxwExxkZhjM= go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.35.0 h1:1fTNlAIJZGWLP5FVu0fikVry1IsiUnXjf7QFvoNN3Xw= go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.35.0/go.mod h1:zjPK58DtkqQFn+YUMbx0M2XV3QgKU0gS9LeGohREyK4= go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.19.0 h1:IeMeyr1aBvBiPVYihXIaeIZba6b8E1bYp7lbdxK8CQg= go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.19.0/go.mod h1:oVdCUtjq9MK9BlS7TtucsQwUcXcymNiEDjgDD2jMtZU= -go.opentelemetry.io/otel/metric v1.37.0 h1:mvwbQS5m0tbmqML4NqK+e3aDiO02vsf/WgbsdpcPoZE= -go.opentelemetry.io/otel/metric v1.37.0/go.mod h1:04wGrZurHYKOc+RKeye86GwKiTb9FKm1WHtO+4EVr2E= -go.opentelemetry.io/otel/sdk v1.37.0 h1:ItB0QUqnjesGRvNcmAcU0LyvkVyGJ2xftD29bWdDvKI= -go.opentelemetry.io/otel/sdk v1.37.0/go.mod h1:VredYzxUvuo2q3WRcDnKDjbdvmO0sCzOvVAiY+yUkAg= -go.opentelemetry.io/otel/trace v1.37.0 h1:HLdcFNbRQBE2imdSEgm/kwqmQj1Or1l/7bW6mxVK7z4= -go.opentelemetry.io/otel/trace v1.37.0/go.mod h1:TlgrlQ+PtQO5XFerSPUYG0JSgGyryXewPGyayAWSBS0= +go.opentelemetry.io/otel/metric v1.38.0 h1:Kl6lzIYGAh5M159u9NgiRkmoMKjvbsKtYRwgfrA6WpA= +go.opentelemetry.io/otel/metric v1.38.0/go.mod h1:kB5n/QoRM8YwmUahxvI3bO34eVtQf2i4utNVLr9gEmI= +go.opentelemetry.io/otel/sdk v1.38.0 h1:l48sr5YbNf2hpCUj/FoGhW9yDkl+Ma+LrVl8qaM5b+E= +go.opentelemetry.io/otel/sdk v1.38.0/go.mod h1:ghmNdGlVemJI3+ZB5iDEuk4bWA3GkTpW+DOoZMYBVVg= +go.opentelemetry.io/otel/trace v1.38.0 h1:Fxk5bKrDZJUH+AMyyIXGcFAPah0oRcT+LuNtJrmcNLE= +go.opentelemetry.io/otel/trace v1.38.0/go.mod h1:j1P9ivuFsTceSWe1oY+EeW3sc+Pp42sO++GHkg4wwhs= go.opentelemetry.io/proto/otlp v1.5.0 h1:xJvq7gMzB31/d406fB8U5CBdyQGw4P399D1aQWU/3i4= go.opentelemetry.io/proto/otlp v1.5.0/go.mod h1:keN8WnHxOy8PG0rQZjJJ5A2ebUoafqWp0eVQ4yIXvJ4= go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto= go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE= -go.uber.org/multierr v1.10.0 h1:S0h4aNzvfcFsC3dRF1jLoaov7oRaKqRGC/pUEJ2yvPQ= -go.uber.org/multierr v1.10.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y= +go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0= +go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y= go.uber.org/zap v1.27.0 h1:aJMhYGrd5QSmlpLMr2MftRKl7t8J8PTZPA732ud/XR8= go.uber.org/zap v1.27.0/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E= go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc= diff --git a/internal/bootstrap/bootstrap.go b/internal/bootstrap/bootstrap.go new file mode 100644 index 0000000..0b068a2 --- /dev/null +++ b/internal/bootstrap/bootstrap.go @@ -0,0 +1,50 @@ +package bootstrap + +import ( + pkgGorm "github.com/break/junhong_cmp_fiber/pkg/gorm" +) + +// Bootstrap 初始化所有业务组件并返回 Handlers +// 这是应用启动时的主入口，负责编排所有组件的初始化流程 +// +// 初始化顺序： +// 1. 初始化 Store 层（数据访问） +// 2. 注册 GORM Callbacks（数据权限过滤等）- 需要 AccountStore +// 3. 初始化 Service 层（业务逻辑） +// 4. 初始化 Handler 层（HTTP 处理） +// +// 参数： +// - deps: 基础依赖（DB, Redis, Logger） +// +// 返回： +// - *Handlers: 所有 HTTP 处理器 +// - error: 初始化错误 +func Bootstrap(deps *Dependencies) (*Handlers, error) { + // 1. 初始化 Store 层 + stores := initStores(deps) + + // 2. 注册 GORM Callbacks（需要 AccountStore 来查询下级 ID） + if err := registerGORMCallbacks(deps, stores); err != nil { + return nil, err + } + + // 3. 初始化 Service 层 + services := initServices(stores) + + // 4. 初始化 Handler 层 + handlers := initHandlers(services) + + return handlers, nil +} + +// registerGORMCallbacks 注册 GORM Callbacks +func registerGORMCallbacks(deps *Dependencies, stores *stores) error { + // 注册数据权限过滤 Callback + if err := pkgGorm.RegisterDataPermissionCallback(deps.DB, stores.Account); err != nil { + return err + } + + // TODO: 在此添加其他 GORM Callbacks + + return nil +} diff --git a/internal/bootstrap/dependencies.go b/internal/bootstrap/dependencies.go new file mode 100644 index 0000000..cecd64c --- /dev/null +++ b/internal/bootstrap/dependencies.go @@ -0,0 +1,15 @@ +package bootstrap + +import ( + "github.com/redis/go-redis/v9" + "go.uber.org/zap" + "gorm.io/gorm" +) + +// Dependencies 封装所有基础依赖 +// 这些是应用启动时初始化的核心组件 +type Dependencies struct { + DB *gorm.DB // PostgreSQL 数据库连接 + Redis *redis.Client // Redis 客户端 + Logger *zap.Logger // 应用日志器 +} diff --git a/internal/bootstrap/handlers.go b/internal/bootstrap/handlers.go new file mode 100644 index 0000000..294f088 --- /dev/null +++ b/internal/bootstrap/handlers.go @@ -0,0 +1,15 @@ +package bootstrap + +import ( + "github.com/break/junhong_cmp_fiber/internal/handler" +) + +// initHandlers 初始化所有 Handler 实例 +func initHandlers(svc *services) *Handlers { + return &Handlers{ + Account: handler.NewAccountHandler(svc.Account), + Role: handler.NewRoleHandler(svc.Role), + Permission: handler.NewPermissionHandler(svc.Permission), + // TODO: 新增 Handler 在此初始化 + } +} diff --git a/internal/bootstrap/services.go b/internal/bootstrap/services.go new file mode 100644 index 0000000..5dcfccd --- /dev/null +++ b/internal/bootstrap/services.go @@ -0,0 +1,26 @@ +package bootstrap + +import ( + accountSvc "github.com/break/junhong_cmp_fiber/internal/service/account" + permissionSvc "github.com/break/junhong_cmp_fiber/internal/service/permission" + roleSvc "github.com/break/junhong_cmp_fiber/internal/service/role" +) + +// services 封装所有 Service 实例 +// 注意：此结构体不导出，仅在 bootstrap 包内部使用 +type services struct { + Account *accountSvc.Service + Role *roleSvc.Service + Permission *permissionSvc.Service + // TODO: 新增 Service 在此添加字段 +} + +// initServices 初始化所有 Service 实例 +func initServices(s *stores) *services { + return &services{ + Account: accountSvc.New(s.Account, s.Role, s.AccountRole), + Role: roleSvc.New(s.Role, s.Permission, s.RolePermission), + Permission: permissionSvc.New(s.Permission), + // TODO: 新增 Service 在此初始化 + } +} diff --git a/internal/bootstrap/stores.go b/internal/bootstrap/stores.go new file mode 100644 index 0000000..6d3f24f --- /dev/null +++ b/internal/bootstrap/stores.go @@ -0,0 +1,28 @@ +package bootstrap + +import ( + "github.com/break/junhong_cmp_fiber/internal/store/postgres" +) + +// stores 封装所有 Store 实例 +// 注意：此结构体不导出，仅在 bootstrap 包内部使用 +type stores struct { + Account *postgres.AccountStore + Role *postgres.RoleStore + Permission *postgres.PermissionStore + AccountRole *postgres.AccountRoleStore + RolePermission *postgres.RolePermissionStore + // TODO: 新增 Store 在此添加字段 +} + +// initStores 初始化所有 Store 实例 +func initStores(deps *Dependencies) *stores { + return &stores{ + Account: postgres.NewAccountStore(deps.DB, deps.Redis), + Role: postgres.NewRoleStore(deps.DB), + Permission: postgres.NewPermissionStore(deps.DB), + AccountRole: postgres.NewAccountRoleStore(deps.DB), + RolePermission: postgres.NewRolePermissionStore(deps.DB), + // TODO: 新增 Store 在此初始化 + } +} diff --git a/internal/bootstrap/types.go b/internal/bootstrap/types.go new file mode 100644 index 0000000..c051c77 --- /dev/null +++ b/internal/bootstrap/types.go @@ -0,0 +1,14 @@ +package bootstrap + +import ( + "github.com/break/junhong_cmp_fiber/internal/handler" +) + +// Handlers 封装所有 HTTP 处理器 +// 用于路由注册 +type Handlers struct { + Account *handler.AccountHandler + Role *handler.RoleHandler + Permission *handler.PermissionHandler + // TODO: 新增 Handler 在此添加字段 +} diff --git a/internal/handler/order.go b/internal/handler/order.go deleted file mode 100644 index 767ad1a..0000000 --- a/internal/handler/order.go +++ /dev/null @@ -1,239 +0,0 @@ -package handler - -import ( - "strconv" - - "github.com/break/junhong_cmp_fiber/internal/model" - "github.com/break/junhong_cmp_fiber/internal/service/order" - "github.com/break/junhong_cmp_fiber/pkg/errors" - "github.com/break/junhong_cmp_fiber/pkg/response" - "github.com/gofiber/fiber/v2" - "go.uber.org/zap" -) - -// OrderHandler 订单处理器 -type OrderHandler struct { - orderService *order.Service - logger *zap.Logger -} - -// NewOrderHandler 创建订单处理器实例 -func NewOrderHandler(orderService *order.Service, logger *zap.Logger) *OrderHandler { - return &OrderHandler{ - orderService: orderService, - logger: logger, - } -} - -// CreateOrder 创建订单 -// POST /api/v1/orders -func (h *OrderHandler) CreateOrder(c *fiber.Ctx) error { - var req model.CreateOrderRequest - - // 解析请求体 - if err := c.BodyParser(&req); err != nil { - h.logger.Warn("解析请求体失败", - zap.String("path", c.Path()), - zap.Error(err)) - return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "请求参数格式错误") - } - - // 验证请求参数 - if err := validate.Struct(&req); err != nil { - h.logger.Warn("参数验证失败", - zap.String("path", c.Path()), - zap.Any("request", req), - zap.Error(err)) - return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, err.Error()) - } - - // 调用服务层创建订单 - orderResp, err := h.orderService.CreateOrder(c.Context(), &req) - if err != nil { - if e, ok := err.(*errors.AppError); ok { - httpStatus := fiber.StatusInternalServerError - if e.Code == errors.CodeNotFound { - httpStatus = fiber.StatusNotFound - } - return response.Error(c, httpStatus, e.Code, e.Message) - } - h.logger.Error("创建订单失败", - zap.String("order_id", req.OrderID), - zap.Error(err)) - return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "创建订单失败") - } - - h.logger.Info("订单创建成功", - zap.Uint("order_id", orderResp.ID), - zap.String("order_no", orderResp.OrderID)) - - return response.Success(c, orderResp) -} - -// GetOrder 获取订单详情 -// GET /api/v1/orders/:id -func (h *OrderHandler) GetOrder(c *fiber.Ctx) error { - // 获取路径参数 - idStr := c.Params("id") - id, err := strconv.ParseUint(idStr, 10, 32) - if err != nil { - h.logger.Warn("订单ID格式错误", - zap.String("id", idStr), - zap.Error(err)) - return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "订单ID格式错误") - } - - // 调用服务层获取订单 - orderResp, err := h.orderService.GetOrderByID(c.Context(), uint(id)) - if err != nil { - if e, ok := err.(*errors.AppError); ok { - httpStatus := fiber.StatusInternalServerError - if e.Code == errors.CodeNotFound { - httpStatus = fiber.StatusNotFound - } - return response.Error(c, httpStatus, e.Code, e.Message) - } - h.logger.Error("获取订单失败", - zap.Uint("order_id", uint(id)), - zap.Error(err)) - return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "获取订单失败") - } - - return response.Success(c, orderResp) -} - -// UpdateOrder 更新订单信息 -// PUT /api/v1/orders/:id -func (h *OrderHandler) UpdateOrder(c *fiber.Ctx) error { - // 获取路径参数 - idStr := c.Params("id") - id, err := strconv.ParseUint(idStr, 10, 32) - if err != nil { - h.logger.Warn("订单ID格式错误", - zap.String("id", idStr), - zap.Error(err)) - return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "订单ID格式错误") - } - - var req model.UpdateOrderRequest - - // 解析请求体 - if err := c.BodyParser(&req); err != nil { - h.logger.Warn("解析请求体失败", - zap.String("path", c.Path()), - zap.Error(err)) - return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "请求参数格式错误") - } - - // 验证请求参数 - if err := validate.Struct(&req); err != nil { - h.logger.Warn("参数验证失败", - zap.String("path", c.Path()), - zap.Any("request", req), - zap.Error(err)) - return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, err.Error()) - } - - // 调用服务层更新订单 - orderResp, err := h.orderService.UpdateOrder(c.Context(), uint(id), &req) - if err != nil { - if e, ok := err.(*errors.AppError); ok { - httpStatus := fiber.StatusInternalServerError - if e.Code == errors.CodeNotFound { - httpStatus = fiber.StatusNotFound - } - return response.Error(c, httpStatus, e.Code, e.Message) - } - h.logger.Error("更新订单失败", - zap.Uint("order_id", uint(id)), - zap.Error(err)) - return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "更新订单失败") - } - - h.logger.Info("订单更新成功", - zap.Uint("order_id", uint(id))) - - return response.Success(c, orderResp) -} - -// ListOrders 获取订单列表（分页） -// GET /api/v1/orders -func (h *OrderHandler) ListOrders(c *fiber.Ctx) error { - // 获取查询参数 - page, err := strconv.Atoi(c.Query("page", "1")) - if err != nil || page < 1 { - page = 1 - } - - pageSize, err := strconv.Atoi(c.Query("page_size", "20")) - if err != nil || pageSize < 1 { - pageSize = 20 - } - if pageSize > 100 { - pageSize = 100 // 限制最大页大小 - } - - // 可选的用户ID过滤 - var userID uint - if userIDStr := c.Query("user_id"); userIDStr != "" { - if id, err := strconv.ParseUint(userIDStr, 10, 32); err == nil { - userID = uint(id) - } - } - - // 调用服务层获取订单列表 - var orders []model.Order - var total int64 - - if userID > 0 { - // 按用户ID查询 - orders, total, err = h.orderService.ListOrdersByUserID(c.Context(), userID, page, pageSize) - } else { - // 查询所有订单 - orders, total, err = h.orderService.ListOrders(c.Context(), page, pageSize) - } - - if err != nil { - if e, ok := err.(*errors.AppError); ok { - return response.Error(c, fiber.StatusInternalServerError, e.Code, e.Message) - } - h.logger.Error("获取订单列表失败", - zap.Int("page", page), - zap.Int("page_size", pageSize), - zap.Uint("user_id", userID), - zap.Error(err)) - return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "获取订单列表失败") - } - - // 构造响应 - totalPages := int(total) / pageSize - if int(total)%pageSize > 0 { - totalPages++ - } - - listResp := model.ListOrdersResponse{ - Orders: make([]model.OrderResponse, 0, len(orders)), - Page: page, - PageSize: pageSize, - Total: total, - TotalPages: totalPages, - } - - // 转换为响应格式 - for _, o := range orders { - listResp.Orders = append(listResp.Orders, model.OrderResponse{ - ID: o.ID, - OrderID: o.OrderID, - UserID: o.UserID, - Amount: o.Amount, - Status: o.Status, - Remark: o.Remark, - PaidAt: o.PaidAt, - CompletedAt: o.CompletedAt, - CreatedAt: o.CreatedAt, - UpdatedAt: o.UpdatedAt, - }) - } - - return response.Success(c, listResp) -} diff --git a/internal/handler/task.go b/internal/handler/task.go index 2c18e91..6451353 100644 --- a/internal/handler/task.go +++ b/internal/handler/task.go @@ -4,6 +4,7 @@ import ( "fmt" "time" + "github.com/go-playground/validator/v10" "github.com/gofiber/fiber/v2" "github.com/google/uuid" "github.com/hibiken/asynq" @@ -20,6 +21,7 @@ import ( type TaskHandler struct { queueClient *queue.Client logger *zap.Logger + validator *validator.Validate } // NewTaskHandler 创建任务处理器实例 @@ -27,6 +29,7 @@ func NewTaskHandler(queueClient *queue.Client, logger *zap.Logger) *TaskHandler return &TaskHandler{ queueClient: queueClient, logger: logger, + validator: validator.New(), } } @@ -72,14 +75,14 @@ func (h *TaskHandler) SubmitEmailTask(c *fiber.Ctx) error { if err := c.BodyParser(&req); err != nil { h.logger.Warn("解析邮件任务请求失败", zap.Error(err)) - return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "请求参数格式错误") + return errors.New(errors.CodeInvalidParam, "请求参数格式错误") } // 验证参数 - if err := validate.Struct(&req); err != nil { + if err := h.validator.Struct(&req); err != nil { h.logger.Warn("邮件任务参数验证失败", zap.Error(err)) - return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, err.Error()) + return errors.New(errors.CodeInvalidParam, err.Error()) } // 生成 RequestID（如果未提供） @@ -111,7 +114,7 @@ func (h *TaskHandler) SubmitEmailTask(c *fiber.Ctx) error { zap.String("to", req.To), zap.String("request_id", req.RequestID), zap.Error(err)) - return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "任务提交失败") + return errors.New(errors.CodeInternalError, "任务提交失败") } h.logger.Info("邮件任务提交成功", @@ -141,14 +144,14 @@ func (h *TaskHandler) SubmitSyncTask(c *fiber.Ctx) error { if err := c.BodyParser(&req); err != nil { h.logger.Warn("解析同步任务请求失败", zap.Error(err)) - return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "请求参数格式错误") + return errors.New(errors.CodeInvalidParam, "请求参数格式错误") } // 验证参数 - if err := validate.Struct(&req); err != nil { + if err := h.validator.Struct(&req); err != nil { h.logger.Warn("同步任务参数验证失败", zap.Error(err)) - return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, err.Error()) + return errors.New(errors.CodeInvalidParam, err.Error()) } // 生成 RequestID（如果未提供） @@ -192,7 +195,7 @@ func (h *TaskHandler) SubmitSyncTask(c *fiber.Ctx) error { zap.String("sync_type", req.SyncType), zap.String("request_id", req.RequestID), zap.Error(err)) - return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "任务提交失败") + return errors.New(errors.CodeInternalError, "任务提交失败") } h.logger.Info("同步任务提交成功", diff --git a/internal/handler/user.go b/internal/handler/user.go deleted file mode 100644 index 80382d1..0000000 --- a/internal/handler/user.go +++ /dev/null @@ -1,250 +0,0 @@ -package handler - -import ( - "strconv" - - "github.com/break/junhong_cmp_fiber/internal/model" - "github.com/break/junhong_cmp_fiber/internal/service/user" - "github.com/break/junhong_cmp_fiber/pkg/errors" - "github.com/break/junhong_cmp_fiber/pkg/response" - "github.com/go-playground/validator/v10" - "github.com/gofiber/fiber/v2" - "go.uber.org/zap" -) - -var validate = validator.New() - -// UserHandler 用户处理器 -type UserHandler struct { - userService *user.Service - logger *zap.Logger -} - -// NewUserHandler 创建用户处理器实例 -func NewUserHandler(userService *user.Service, logger *zap.Logger) *UserHandler { - return &UserHandler{ - userService: userService, - logger: logger, - } -} - -// CreateUser 创建用户 -// POST /api/v1/users -func (h *UserHandler) CreateUser(c *fiber.Ctx) error { - var req model.CreateUserRequest - - // 解析请求体 - if err := c.BodyParser(&req); err != nil { - h.logger.Warn("解析请求体失败", - zap.String("path", c.Path()), - zap.Error(err)) - return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "请求参数格式错误") - } - - // 验证请求参数 - if err := validate.Struct(&req); err != nil { - h.logger.Warn("参数验证失败", - zap.String("path", c.Path()), - zap.Any("request", req), - zap.Error(err)) - return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, err.Error()) - } - - // 调用服务层创建用户 - userResp, err := h.userService.CreateUser(c.Context(), &req) - if err != nil { - if e, ok := err.(*errors.AppError); ok { - return response.Error(c, fiber.StatusInternalServerError, e.Code, e.Message) - } - h.logger.Error("创建用户失败", - zap.String("username", req.Username), - zap.Error(err)) - return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "创建用户失败") - } - - h.logger.Info("用户创建成功", - zap.Uint("user_id", userResp.ID), - zap.String("username", userResp.Username)) - - return response.Success(c, userResp) -} - -// GetUser 获取用户详情 -// GET /api/v1/users/:id -func (h *UserHandler) GetUser(c *fiber.Ctx) error { - // 获取路径参数 - idStr := c.Params("id") - id, err := strconv.ParseUint(idStr, 10, 32) - if err != nil { - h.logger.Warn("用户ID格式错误", - zap.String("id", idStr), - zap.Error(err)) - return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "用户ID格式错误") - } - - // 调用服务层获取用户 - userResp, err := h.userService.GetUserByID(c.Context(), uint(id)) - if err != nil { - if e, ok := err.(*errors.AppError); ok { - httpStatus := fiber.StatusInternalServerError - if e.Code == errors.CodeNotFound { - httpStatus = fiber.StatusNotFound - } - return response.Error(c, httpStatus, e.Code, e.Message) - } - h.logger.Error("获取用户失败", - zap.Uint("user_id", uint(id)), - zap.Error(err)) - return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "获取用户失败") - } - - return response.Success(c, userResp) -} - -// UpdateUser 更新用户信息 -// PUT /api/v1/users/:id -func (h *UserHandler) UpdateUser(c *fiber.Ctx) error { - // 获取路径参数 - idStr := c.Params("id") - id, err := strconv.ParseUint(idStr, 10, 32) - if err != nil { - h.logger.Warn("用户ID格式错误", - zap.String("id", idStr), - zap.Error(err)) - return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "用户ID格式错误") - } - - var req model.UpdateUserRequest - - // 解析请求体 - if err := c.BodyParser(&req); err != nil { - h.logger.Warn("解析请求体失败", - zap.String("path", c.Path()), - zap.Error(err)) - return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "请求参数格式错误") - } - - // 验证请求参数 - if err := validate.Struct(&req); err != nil { - h.logger.Warn("参数验证失败", - zap.String("path", c.Path()), - zap.Any("request", req), - zap.Error(err)) - return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, err.Error()) - } - - // 调用服务层更新用户 - userResp, err := h.userService.UpdateUser(c.Context(), uint(id), &req) - if err != nil { - if e, ok := err.(*errors.AppError); ok { - httpStatus := fiber.StatusInternalServerError - if e.Code == errors.CodeNotFound { - httpStatus = fiber.StatusNotFound - } - return response.Error(c, httpStatus, e.Code, e.Message) - } - h.logger.Error("更新用户失败", - zap.Uint("user_id", uint(id)), - zap.Error(err)) - return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "更新用户失败") - } - - h.logger.Info("用户更新成功", - zap.Uint("user_id", uint(id))) - - return response.Success(c, userResp) -} - -// DeleteUser 删除用户（软删除） -// DELETE /api/v1/users/:id -func (h *UserHandler) DeleteUser(c *fiber.Ctx) error { - // 获取路径参数 - idStr := c.Params("id") - id, err := strconv.ParseUint(idStr, 10, 32) - if err != nil { - h.logger.Warn("用户ID格式错误", - zap.String("id", idStr), - zap.Error(err)) - return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "用户ID格式错误") - } - - // 调用服务层删除用户 - if err := h.userService.DeleteUser(c.Context(), uint(id)); err != nil { - if e, ok := err.(*errors.AppError); ok { - httpStatus := fiber.StatusInternalServerError - if e.Code == errors.CodeNotFound { - httpStatus = fiber.StatusNotFound - } - return response.Error(c, httpStatus, e.Code, e.Message) - } - h.logger.Error("删除用户失败", - zap.Uint("user_id", uint(id)), - zap.Error(err)) - return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "删除用户失败") - } - - h.logger.Info("用户删除成功", - zap.Uint("user_id", uint(id))) - - return response.Success(c, nil) -} - -// ListUsers 获取用户列表（分页） -// GET /api/v1/users -func (h *UserHandler) ListUsers(c *fiber.Ctx) error { - // 获取查询参数 - page, err := strconv.Atoi(c.Query("page", "1")) - if err != nil || page < 1 { - page = 1 - } - - pageSize, err := strconv.Atoi(c.Query("page_size", "20")) - if err != nil || pageSize < 1 { - pageSize = 20 - } - if pageSize > 100 { - pageSize = 100 // 限制最大页大小 - } - - // 调用服务层获取用户列表 - users, total, err := h.userService.ListUsers(c.Context(), page, pageSize) - if err != nil { - if e, ok := err.(*errors.AppError); ok { - return response.Error(c, fiber.StatusInternalServerError, e.Code, e.Message) - } - h.logger.Error("获取用户列表失败", - zap.Int("page", page), - zap.Int("page_size", pageSize), - zap.Error(err)) - return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "获取用户列表失败") - } - - // 构造响应 - totalPages := int(total) / pageSize - if int(total)%pageSize > 0 { - totalPages++ - } - - listResp := model.ListUsersResponse{ - Users: make([]model.UserResponse, 0, len(users)), - Page: page, - PageSize: pageSize, - Total: total, - TotalPages: totalPages, - } - - // 转换为响应格式 - for _, u := range users { - listResp.Users = append(listResp.Users, model.UserResponse{ - ID: u.ID, - Username: u.Username, - Email: u.Email, - Status: u.Status, - CreatedAt: u.CreatedAt, - UpdatedAt: u.UpdatedAt, - LastLoginAt: u.LastLoginAt, - }) - } - - return response.Success(c, listResp) -} diff --git a/internal/middleware/auth.go b/internal/middleware/auth.go deleted file mode 100644 index 312862e..0000000 --- a/internal/middleware/auth.go +++ /dev/null @@ -1,53 +0,0 @@ -package middleware - -import ( - "github.com/gofiber/fiber/v2" - "github.com/gofiber/fiber/v2/middleware/keyauth" - "go.uber.org/zap" - - "github.com/break/junhong_cmp_fiber/pkg/constants" - "github.com/break/junhong_cmp_fiber/pkg/errors" - "github.com/break/junhong_cmp_fiber/pkg/response" - "github.com/break/junhong_cmp_fiber/pkg/validator" -) - -// KeyAuth 创建基于 Redis 的令牌认证中间件 -func KeyAuth(v *validator.TokenValidator, logger *zap.Logger) fiber.Handler { - return keyauth.New(keyauth.Config{ - KeyLookup: "header:token", - Validator: func(c *fiber.Ctx, key string) (bool, error) { - // 验证令牌 - userID, err := v.Validate(key) - if err != nil { - // 获取请求 ID 用于日志 - requestID := "" - if rid := c.Locals(constants.ContextKeyRequestID); rid != nil { - requestID = rid.(string) - } - - logger.Warn("令牌验证失败", - zap.String("request_id", requestID), - zap.Error(err), - ) - return false, err - } - - // 在上下文中存储用户 ID - c.Locals(constants.ContextKeyUserID, userID) - return true, nil - }, - ErrorHandler: func(c *fiber.Ctx, err error) error { - // 将错误映射到统一响应格式 - switch err { - case keyauth.ErrMissingOrMalformedAPIKey: - return response.Error(c, 400, errors.CodeMissingToken, errors.GetMessage(errors.CodeMissingToken, "zh")) - case errors.ErrInvalidToken: - return response.Error(c, 400, errors.CodeInvalidToken, errors.GetMessage(errors.CodeInvalidToken, "zh")) - case errors.ErrRedisUnavailable: - return response.Error(c, 503, errors.CodeAuthServiceUnavailable, errors.GetMessage(errors.CodeAuthServiceUnavailable, "zh")) - default: - return response.Error(c, 500, errors.CodeInternalError, errors.GetMessage(errors.CodeInternalError, "zh")) - } - }, - }) -} diff --git a/internal/middleware/ratelimit.go b/internal/middleware/ratelimit.go index 921c961..95252d8 100644 --- a/internal/middleware/ratelimit.go +++ b/internal/middleware/ratelimit.go @@ -9,7 +9,6 @@ import ( "github.com/break/junhong_cmp_fiber/pkg/constants" "github.com/break/junhong_cmp_fiber/pkg/errors" - "github.com/break/junhong_cmp_fiber/pkg/response" ) // RateLimiter 创建基于 IP 的限流中间件 @@ -23,7 +22,7 @@ func RateLimiter(max int, expiration time.Duration, storage fiber.Storage) fiber return constants.RedisRateLimitKey(c.IP()) }, LimitReached: func(c *fiber.Ctx) error { - return response.Error(c, 429, errors.CodeTooManyRequests, errors.GetMessage(errors.CodeTooManyRequests, "zh")) + return errors.New(errors.CodeTooManyRequests, errors.GetMessage(errors.CodeTooManyRequests, "zh")) }, Storage: storage, // 支持内存或 Redis 存储 }) diff --git a/internal/model/order.go b/internal/model/order.go deleted file mode 100644 index 97fb43c..0000000 --- a/internal/model/order.go +++ /dev/null @@ -1,30 +0,0 @@ -package model - -import ( - "time" -) - -// Order 订单实体 -type Order struct { - BaseModel - - // 业务唯一键 - OrderID string `gorm:"uniqueIndex:uk_order_order_id;not null;size:50" json:"order_id"` - - // 关联关系 (仅存储 ID,不使用 GORM 关联) - UserID uint `gorm:"not null;index:idx_order_user_id" json:"user_id"` - - // 订单信息 - Amount int64 `gorm:"not null" json:"amount"` // 金额（分） - Status string `gorm:"not null;size:20;default:'pending';index:idx_order_status" json:"status"` - Remark string `gorm:"size:500" json:"remark,omitempty"` - - // 时间字段 - PaidAt *time.Time `gorm:"column:paid_at" json:"paid_at,omitempty"` - CompletedAt *time.Time `gorm:"column:completed_at" json:"completed_at,omitempty"` -} - -// TableName 指定表名 -func (Order) TableName() string { - return "tb_order" -} diff --git a/internal/model/order_dto.go b/internal/model/order_dto.go deleted file mode 100644 index 6f2111d..0000000 --- a/internal/model/order_dto.go +++ /dev/null @@ -1,43 +0,0 @@ -package model - -import ( - "time" -) - -// CreateOrderRequest 创建订单请求 -type CreateOrderRequest struct { - OrderID string `json:"order_id" validate:"required,min=10,max=50"` - UserID uint `json:"user_id" validate:"required,gt=0"` - Amount int64 `json:"amount" validate:"required,gte=0"` - Remark string `json:"remark" validate:"omitempty,max=500"` -} - -// UpdateOrderRequest 更新订单请求 -type UpdateOrderRequest struct { - Status *string `json:"status" validate:"omitempty,oneof=pending paid processing completed cancelled"` - Remark *string `json:"remark" validate:"omitempty,max=500"` -} - -// OrderResponse 订单响应 -type OrderResponse struct { - ID uint `json:"id"` - OrderID string `json:"order_id"` - UserID uint `json:"user_id"` - Amount int64 `json:"amount"` - Status string `json:"status"` - Remark string `json:"remark,omitempty"` - PaidAt *time.Time `json:"paid_at,omitempty"` - CompletedAt *time.Time `json:"completed_at,omitempty"` - CreatedAt time.Time `json:"created_at"` - UpdatedAt time.Time `json:"updated_at"` - User *UserResponse `json:"user,omitempty"` // 可选的用户信息 -} - -// ListOrdersResponse 订单列表响应 -type ListOrdersResponse struct { - Orders []OrderResponse `json:"orders"` - Page int `json:"page"` - PageSize int `json:"page_size"` - Total int64 `json:"total"` - TotalPages int `json:"total_pages"` -} diff --git a/internal/model/user.go b/internal/model/user.go deleted file mode 100644 index 05c687d..0000000 --- a/internal/model/user.go +++ /dev/null @@ -1,26 +0,0 @@ -package model - -import ( - "time" -) - -// User 用户实体 -type User struct { - BaseModel - - // 基本信息 - Username string `gorm:"uniqueIndex:uk_user_username;not null;size:50" json:"username"` - Email string `gorm:"uniqueIndex:uk_user_email;not null;size:100" json:"email"` - Password string `gorm:"not null;size:255" json:"-"` // 不返回给客户端 - - // 状态字段 - Status string `gorm:"not null;size:20;default:'active';index:idx_user_status" json:"status"` - - // 元数据 - LastLoginAt *time.Time `gorm:"column:last_login_at" json:"last_login_at,omitempty"` -} - -// TableName 指定表名 -func (User) TableName() string { - return "tb_user" -} diff --git a/internal/model/user_dto.go b/internal/model/user_dto.go deleted file mode 100644 index 7b5c0f8..0000000 --- a/internal/model/user_dto.go +++ /dev/null @@ -1,38 +0,0 @@ -package model - -import ( - "time" -) - -// CreateUserRequest 创建用户请求 -type CreateUserRequest struct { - Username string `json:"username" validate:"required,min=3,max=50,alphanum"` - Email string `json:"email" validate:"required,email"` - Password string `json:"password" validate:"required,min=8"` -} - -// UpdateUserRequest 更新用户请求 -type UpdateUserRequest struct { - Email *string `json:"email" validate:"omitempty,email"` - Status *string `json:"status" validate:"omitempty,oneof=active inactive suspended"` -} - -// UserResponse 用户响应 -type UserResponse struct { - ID uint `json:"id"` - Username string `json:"username"` - Email string `json:"email"` - Status string `json:"status"` - CreatedAt time.Time `json:"created_at"` - UpdatedAt time.Time `json:"updated_at"` - LastLoginAt *time.Time `json:"last_login_at,omitempty"` -} - -// ListUsersResponse 用户列表响应 -type ListUsersResponse struct { - Users []UserResponse `json:"users"` - Page int `json:"page"` - PageSize int `json:"page_size"` - Total int64 `json:"total"` - TotalPages int `json:"total_pages"` -} diff --git a/internal/routes/routes.go b/internal/routes/routes.go index 5788ed2..d8b5ee0 100644 --- a/internal/routes/routes.go +++ b/internal/routes/routes.go @@ -3,21 +3,12 @@ package routes import ( "github.com/gofiber/fiber/v2" - "github.com/break/junhong_cmp_fiber/internal/handler" + "github.com/break/junhong_cmp_fiber/internal/bootstrap" ) -// Services 容器，包含所有业务 Handler -// 由 main 函数初始化并传递给路由注册函数 -type Services struct { - // RBAC 相关 Handler - AccountHandler *handler.AccountHandler - RoleHandler *handler.RoleHandler - PermissionHandler *handler.PermissionHandler -} - // RegisterRoutes 路由注册总入口 // 按业务模块调用各自的路由注册函数 -func RegisterRoutes(app *fiber.App, services *Services) { +func RegisterRoutes(app *fiber.App, handlers *bootstrap.Handlers) { // API 路由组 api := app.Group("/api/v1") @@ -26,13 +17,13 @@ func RegisterRoutes(app *fiber.App, services *Services) { registerTaskRoutes(api) // RBAC 路由 - if services.AccountHandler != nil { - registerAccountRoutes(api, services.AccountHandler) + if handlers.Account != nil { + registerAccountRoutes(api, handlers.Account) } - if services.RoleHandler != nil { - registerRoleRoutes(api, services.RoleHandler) + if handlers.Role != nil { + registerRoleRoutes(api, handlers.Role) } - if services.PermissionHandler != nil { - registerPermissionRoutes(api, services.PermissionHandler) + if handlers.Permission != nil { + registerPermissionRoutes(api, handlers.Permission) } } diff --git a/internal/service/order/service.go b/internal/service/order/service.go deleted file mode 100644 index 02adb6d..0000000 --- a/internal/service/order/service.go +++ /dev/null @@ -1,254 +0,0 @@ -package order - -import ( - "context" - "fmt" - "time" - - "github.com/break/junhong_cmp_fiber/internal/model" - "github.com/break/junhong_cmp_fiber/internal/store/postgres" - "github.com/break/junhong_cmp_fiber/pkg/constants" - pkgErrors "github.com/break/junhong_cmp_fiber/pkg/errors" - "go.uber.org/zap" - "gorm.io/gorm" -) - -// Service 订单服务 -type Service struct { - store *postgres.Store - logger *zap.Logger -} - -// NewService 创建订单服务 -func NewService(store *postgres.Store, logger *zap.Logger) *Service { - return &Service{ - store: store, - logger: logger, - } -} - -// CreateOrder 创建订单 -func (s *Service) CreateOrder(ctx context.Context, req *model.CreateOrderRequest) (*model.Order, error) { - // 验证用户是否存在 - _, err := s.store.User.GetByID(ctx, req.UserID) - if err != nil { - if err == gorm.ErrRecordNotFound { - return nil, pkgErrors.New(pkgErrors.CodeNotFound, "用户不存在") - } - s.logger.Error("查询用户失败", - zap.Uint("user_id", req.UserID), - zap.Error(err)) - return nil, pkgErrors.New(pkgErrors.CodeInternalError, "查询用户失败") - } - - // 创建订单 - order := &model.Order{ - OrderID: req.OrderID, - UserID: req.UserID, - Amount: req.Amount, - Status: constants.OrderStatusPending, - Remark: req.Remark, - } - - if err := s.store.Order.Create(ctx, order); err != nil { - s.logger.Error("创建订单失败", - zap.String("order_id", req.OrderID), - zap.Error(err)) - return nil, pkgErrors.New(pkgErrors.CodeInternalError, "创建订单失败") - } - - s.logger.Info("订单创建成功", - zap.Uint("id", order.ID), - zap.String("order_id", order.OrderID), - zap.Uint("user_id", order.UserID)) - - return order, nil -} - -// GetOrderByID 根据 ID 获取订单 -func (s *Service) GetOrderByID(ctx context.Context, id uint) (*model.Order, error) { - order, err := s.store.Order.GetByID(ctx, id) - if err != nil { - if err == gorm.ErrRecordNotFound { - return nil, pkgErrors.New(pkgErrors.CodeNotFound, "订单不存在") - } - s.logger.Error("获取订单失败", - zap.Uint("order_id", id), - zap.Error(err)) - return nil, pkgErrors.New(pkgErrors.CodeInternalError, "获取订单失败") - } - return order, nil -} - -// UpdateOrder 更新订单 -func (s *Service) UpdateOrder(ctx context.Context, id uint, req *model.UpdateOrderRequest) (*model.Order, error) { - // 查询订单 - order, err := s.store.Order.GetByID(ctx, id) - if err != nil { - if err == gorm.ErrRecordNotFound { - return nil, pkgErrors.New(pkgErrors.CodeNotFound, "订单不存在") - } - s.logger.Error("查询订单失败", - zap.Uint("order_id", id), - zap.Error(err)) - return nil, pkgErrors.New(pkgErrors.CodeInternalError, "查询订单失败") - } - - // 更新字段 - if req.Status != nil { - order.Status = *req.Status - // 根据状态自动设置时间字段 - now := time.Now() - switch *req.Status { - case constants.OrderStatusPaid: - order.PaidAt = &now - case constants.OrderStatusCompleted: - order.CompletedAt = &now - } - } - if req.Remark != nil { - order.Remark = *req.Remark - } - - // 保存更新 - if err := s.store.Order.Update(ctx, order); err != nil { - s.logger.Error("更新订单失败", - zap.Uint("order_id", id), - zap.Error(err)) - return nil, pkgErrors.New(pkgErrors.CodeInternalError, "更新订单失败") - } - - s.logger.Info("订单更新成功", - zap.Uint("id", order.ID), - zap.String("order_id", order.OrderID)) - - return order, nil -} - -// DeleteOrder 删除订单（软删除） -func (s *Service) DeleteOrder(ctx context.Context, id uint) error { - // 检查订单是否存在 - _, err := s.store.Order.GetByID(ctx, id) - if err != nil { - if err == gorm.ErrRecordNotFound { - return pkgErrors.New(pkgErrors.CodeNotFound, "订单不存在") - } - s.logger.Error("查询订单失败", - zap.Uint("order_id", id), - zap.Error(err)) - return pkgErrors.New(pkgErrors.CodeInternalError, "查询订单失败") - } - - // 软删除 - if err := s.store.Order.Delete(ctx, id); err != nil { - s.logger.Error("删除订单失败", - zap.Uint("order_id", id), - zap.Error(err)) - return pkgErrors.New(pkgErrors.CodeInternalError, "删除订单失败") - } - - s.logger.Info("订单删除成功", zap.Uint("order_id", id)) - return nil -} - -// ListOrders 分页获取订单列表 -func (s *Service) ListOrders(ctx context.Context, page, pageSize int) ([]model.Order, int64, error) { - // 参数验证 - if page < 1 { - page = 1 - } - if pageSize < 1 { - pageSize = constants.DefaultPageSize - } - if pageSize > constants.MaxPageSize { - pageSize = constants.MaxPageSize - } - - orders, total, err := s.store.Order.List(ctx, page, pageSize) - if err != nil { - s.logger.Error("获取订单列表失败", - zap.Int("page", page), - zap.Int("page_size", pageSize), - zap.Error(err)) - return nil, 0, pkgErrors.New(pkgErrors.CodeInternalError, "获取订单列表失败") - } - - return orders, total, nil -} - -// ListOrdersByUserID 根据用户ID分页获取订单列表 -func (s *Service) ListOrdersByUserID(ctx context.Context, userID uint, page, pageSize int) ([]model.Order, int64, error) { - // 参数验证 - if page < 1 { - page = 1 - } - if pageSize < 1 { - pageSize = constants.DefaultPageSize - } - if pageSize > constants.MaxPageSize { - pageSize = constants.MaxPageSize - } - - orders, total, err := s.store.Order.ListByUserID(ctx, userID, page, pageSize) - if err != nil { - s.logger.Error("获取用户订单列表失败", - zap.Uint("user_id", userID), - zap.Int("page", page), - zap.Int("page_size", pageSize), - zap.Error(err)) - return nil, 0, pkgErrors.New(pkgErrors.CodeInternalError, "获取订单列表失败") - } - - return orders, total, nil -} - -// CreateOrderWithUser 创建订单并更新用户统计（事务示例） -func (s *Service) CreateOrderWithUser(ctx context.Context, req *model.CreateOrderRequest) (*model.Order, error) { - var order *model.Order - - // 使用事务 - err := s.store.Transaction(ctx, func(tx *postgres.Store) error { - // 1. 验证用户是否存在 - user, err := tx.User.GetByID(ctx, req.UserID) - if err != nil { - if err == gorm.ErrRecordNotFound { - return pkgErrors.New(pkgErrors.CodeNotFound, "用户不存在") - } - return err - } - - // 2. 创建订单 - order = &model.Order{ - OrderID: req.OrderID, - UserID: req.UserID, - Amount: req.Amount, - Status: constants.OrderStatusPending, - Remark: req.Remark, - } - - if err := tx.Order.Create(ctx, order); err != nil { - return err - } - - // 3. 更新用户状态（示例：可以在这里更新用户的订单计数等） - s.logger.Debug("订单创建成功，用户信息", - zap.String("username", user.Username), - zap.String("order_id", order.OrderID)) - - return nil // 提交事务 - }) - - if err != nil { - s.logger.Error("事务创建订单失败", - zap.String("order_id", req.OrderID), - zap.Error(err)) - return nil, fmt.Errorf("创建订单失败: %w", err) - } - - s.logger.Info("事务创建订单成功", - zap.Uint("id", order.ID), - zap.String("order_id", order.OrderID), - zap.Uint("user_id", order.UserID)) - - return order, nil -} diff --git a/internal/service/user/service.go b/internal/service/user/service.go deleted file mode 100644 index 5826615..0000000 --- a/internal/service/user/service.go +++ /dev/null @@ -1,161 +0,0 @@ -package user - -import ( - "context" - - "github.com/break/junhong_cmp_fiber/internal/model" - "github.com/break/junhong_cmp_fiber/internal/store/postgres" - "github.com/break/junhong_cmp_fiber/pkg/constants" - pkgErrors "github.com/break/junhong_cmp_fiber/pkg/errors" - "go.uber.org/zap" - "golang.org/x/crypto/bcrypt" - "gorm.io/gorm" -) - -// Service 用户服务 -type Service struct { - store *postgres.Store - logger *zap.Logger -} - -// NewService 创建用户服务 -func NewService(store *postgres.Store, logger *zap.Logger) *Service { - return &Service{ - store: store, - logger: logger, - } -} - -// CreateUser 创建用户 -func (s *Service) CreateUser(ctx context.Context, req *model.CreateUserRequest) (*model.User, error) { - // 密码哈希 - hashedPassword, err := bcrypt.GenerateFromPassword([]byte(req.Password), bcrypt.DefaultCost) - if err != nil { - s.logger.Error("密码哈希失败", zap.Error(err)) - return nil, pkgErrors.New(pkgErrors.CodeInternalError, "密码加密失败") - } - - // 创建用户 - user := &model.User{ - Username: req.Username, - Email: req.Email, - Password: string(hashedPassword), - Status: constants.UserStatusActive, - } - - if err := s.store.User.Create(ctx, user); err != nil { - s.logger.Error("创建用户失败", - zap.String("username", req.Username), - zap.Error(err)) - return nil, pkgErrors.New(pkgErrors.CodeInternalError, "创建用户失败") - } - - s.logger.Info("用户创建成功", - zap.Uint("user_id", user.ID), - zap.String("username", user.Username)) - - return user, nil -} - -// GetUserByID 根据 ID 获取用户 -func (s *Service) GetUserByID(ctx context.Context, id uint) (*model.User, error) { - user, err := s.store.User.GetByID(ctx, id) - if err != nil { - if err == gorm.ErrRecordNotFound { - return nil, pkgErrors.New(pkgErrors.CodeNotFound, "用户不存在") - } - s.logger.Error("获取用户失败", - zap.Uint("user_id", id), - zap.Error(err)) - return nil, pkgErrors.New(pkgErrors.CodeInternalError, "获取用户失败") - } - return user, nil -} - -// UpdateUser 更新用户 -func (s *Service) UpdateUser(ctx context.Context, id uint, req *model.UpdateUserRequest) (*model.User, error) { - // 查询用户 - user, err := s.store.User.GetByID(ctx, id) - if err != nil { - if err == gorm.ErrRecordNotFound { - return nil, pkgErrors.New(pkgErrors.CodeNotFound, "用户不存在") - } - s.logger.Error("查询用户失败", - zap.Uint("user_id", id), - zap.Error(err)) - return nil, pkgErrors.New(pkgErrors.CodeInternalError, "查询用户失败") - } - - // 更新字段 - if req.Email != nil { - user.Email = *req.Email - } - if req.Status != nil { - user.Status = *req.Status - } - - // 保存更新 - if err := s.store.User.Update(ctx, user); err != nil { - s.logger.Error("更新用户失败", - zap.Uint("user_id", id), - zap.Error(err)) - return nil, pkgErrors.New(pkgErrors.CodeInternalError, "更新用户失败") - } - - s.logger.Info("用户更新成功", - zap.Uint("user_id", user.ID), - zap.String("username", user.Username)) - - return user, nil -} - -// DeleteUser 删除用户（软删除） -func (s *Service) DeleteUser(ctx context.Context, id uint) error { - // 检查用户是否存在 - _, err := s.store.User.GetByID(ctx, id) - if err != nil { - if err == gorm.ErrRecordNotFound { - return pkgErrors.New(pkgErrors.CodeNotFound, "用户不存在") - } - s.logger.Error("查询用户失败", - zap.Uint("user_id", id), - zap.Error(err)) - return pkgErrors.New(pkgErrors.CodeInternalError, "查询用户失败") - } - - // 软删除 - if err := s.store.User.Delete(ctx, id); err != nil { - s.logger.Error("删除用户失败", - zap.Uint("user_id", id), - zap.Error(err)) - return pkgErrors.New(pkgErrors.CodeInternalError, "删除用户失败") - } - - s.logger.Info("用户删除成功", zap.Uint("user_id", id)) - return nil -} - -// ListUsers 分页获取用户列表 -func (s *Service) ListUsers(ctx context.Context, page, pageSize int) ([]model.User, int64, error) { - // 参数验证 - if page < 1 { - page = 1 - } - if pageSize < 1 { - pageSize = constants.DefaultPageSize - } - if pageSize > constants.MaxPageSize { - pageSize = constants.MaxPageSize - } - - users, total, err := s.store.User.List(ctx, page, pageSize) - if err != nil { - s.logger.Error("获取用户列表失败", - zap.Int("page", page), - zap.Int("page_size", pageSize), - zap.Error(err)) - return nil, 0, pkgErrors.New(pkgErrors.CodeInternalError, "获取用户列表失败") - } - - return users, total, nil -} diff --git a/internal/store/postgres/order_store.go b/internal/store/postgres/order_store.go deleted file mode 100644 index 69ab158..0000000 --- a/internal/store/postgres/order_store.go +++ /dev/null @@ -1,104 +0,0 @@ -package postgres - -import ( - "context" - - "github.com/break/junhong_cmp_fiber/internal/model" - "gorm.io/gorm" -) - -// OrderStore 订单数据访问层 -type OrderStore struct { - db *gorm.DB -} - -// NewOrderStore 创建订单 Store -func NewOrderStore(db *gorm.DB) *OrderStore { - return &OrderStore{db: db} -} - -// Create 创建订单 -func (s *OrderStore) Create(ctx context.Context, order *model.Order) error { - return s.db.WithContext(ctx).Create(order).Error -} - -// GetByID 根据 ID 获取订单 -func (s *OrderStore) GetByID(ctx context.Context, id uint) (*model.Order, error) { - var order model.Order - err := s.db.WithContext(ctx).First(&order, id).Error - if err != nil { - return nil, err - } - return &order, nil -} - -// GetByOrderID 根据订单号获取订单 -func (s *OrderStore) GetByOrderID(ctx context.Context, orderID string) (*model.Order, error) { - var order model.Order - err := s.db.WithContext(ctx).Where("order_id = ?", orderID).First(&order).Error - if err != nil { - return nil, err - } - return &order, nil -} - -// ListByUserID 根据用户 ID 分页获取订单列表 -func (s *OrderStore) ListByUserID(ctx context.Context, userID uint, page, pageSize int) ([]model.Order, int64, error) { - var orders []model.Order - var total int64 - - // 计算总数 - if err := s.db.WithContext(ctx).Model(&model.Order{}).Where("user_id = ?", userID).Count(&total).Error; err != nil { - return nil, 0, err - } - - // 分页查询 - offset := (page - 1) * pageSize - err := s.db.WithContext(ctx). - Where("user_id = ?", userID). - Offset(offset). - Limit(pageSize). - Order("created_at DESC"). - Find(&orders).Error - - if err != nil { - return nil, 0, err - } - - return orders, total, nil -} - -// List 分页获取订单列表（全部订单） -func (s *OrderStore) List(ctx context.Context, page, pageSize int) ([]model.Order, int64, error) { - var orders []model.Order - var total int64 - - // 计算总数 - if err := s.db.WithContext(ctx).Model(&model.Order{}).Count(&total).Error; err != nil { - return nil, 0, err - } - - // 分页查询 - offset := (page - 1) * pageSize - err := s.db.WithContext(ctx). - Offset(offset). - Limit(pageSize). - Order("created_at DESC"). - Find(&orders).Error - - if err != nil { - return nil, 0, err - } - - return orders, total, nil -} - -// Update 更新订单 -func (s *OrderStore) Update(ctx context.Context, order *model.Order) error { - return s.db.WithContext(ctx).Save(order).Error -} - -// Delete 软删除订单 -func (s *OrderStore) Delete(ctx context.Context, id uint) error { - return s.db.WithContext(ctx).Delete(&model.Order{}, id).Error -} diff --git a/internal/store/postgres/scopes.go b/internal/store/postgres/scopes.go deleted file mode 100644 index a9b014f..0000000 --- a/internal/store/postgres/scopes.go +++ /dev/null @@ -1,86 +0,0 @@ -package postgres - -import ( - "context" - - "github.com/break/junhong_cmp_fiber/pkg/constants" - "github.com/break/junhong_cmp_fiber/pkg/logger" - "github.com/break/junhong_cmp_fiber/pkg/middleware" - "go.uber.org/zap" - "gorm.io/gorm" -) - -// DataPermissionScope 数据权限过滤 Scope -// 根据 context 中的用户信息自动过滤数据 -// - root 用户跳过过滤 -// - 普通用户只能查看自己和下级的数据 -// - 同时限制 shop_id 相同 -func DataPermissionScope(ctx context.Context, accountStore *AccountStore) func(db *gorm.DB) *gorm.DB { - return func(db *gorm.DB) *gorm.DB { - // 1. 检查是否为 root 用户，root 用户跳过数据权限过滤 - if middleware.IsRootUser(ctx) { - return db - } - - // 2. 获取当前用户 ID - userID := middleware.GetUserIDFromContext(ctx) - if userID == 0 { - // 未登录用户返回空结果 - logger.GetAppLogger().Warn("数据权限过滤：未获取到用户 ID") - return db.Where("1 = 0") - } - - // 3. 获取当前用户的 shop_id - shopID := middleware.GetShopIDFromContext(ctx) - - // 4. 获取当前用户及所有下级的 ID - subordinateIDs, err := accountStore.GetSubordinateIDs(ctx, userID) - if err != nil { - // 查询失败时，降级为只能看自己的数据 - - logger.GetAppLogger().Error("数据权限过滤：获取下级 ID 失败", - zap.Uint("user_id", userID), - zap.Error(err)) - subordinateIDs = []uint{userID} - } - - // 5. 应用数据权限过滤条件 - // owner_id IN (用户自己及所有下级) AND shop_id = 当前用户 shop_id - if len(subordinateIDs) == 0 { - subordinateIDs = []uint{userID} - } - - // 根据是否有 shop_id 过滤条件决定 SQL - if shopID != 0 { - return db.Where("owner_id IN ? AND shop_id = ?", subordinateIDs, shopID) - } - - // 如果 shop_id 为 0，只根据 owner_id 过滤 - return db.Where("owner_id IN ?", subordinateIDs) - } -} - -// WithoutDataPermission 跳过数据权限过滤的 Scope -// 用于需要查询所有数据的场景（如管理后台统计、系统任务等） -func WithoutDataPermission() func(db *gorm.DB) *gorm.DB { - return func(db *gorm.DB) *gorm.DB { - // 什么都不做，直接返回原 db - return db - } -} - -// SoftDeleteScope 软删除过滤 Scope（GORM 默认已支持，此处作为示例） -// 只查询未软删除的记录 -func SoftDeleteScope() func(db *gorm.DB) *gorm.DB { - return func(db *gorm.DB) *gorm.DB { - return db.Where("deleted_at IS NULL") - } -} - -// StatusEnabledScope 状态启用过滤 Scope -// 只查询状态为启用的记录 -func StatusEnabledScope() func(db *gorm.DB) *gorm.DB { - return func(db *gorm.DB) *gorm.DB { - return db.Where("status = ?", constants.StatusEnabled) - } -} diff --git a/internal/store/postgres/store.go b/internal/store/postgres/store.go deleted file mode 100644 index badf563..0000000 --- a/internal/store/postgres/store.go +++ /dev/null @@ -1,53 +0,0 @@ -package postgres - -import ( - "context" - - "go.uber.org/zap" - "gorm.io/gorm" -) - -// Store PostgreSQL 数据访问层整合结构 -type Store struct { - db *gorm.DB - logger *zap.Logger - - User *UserStore - Order *OrderStore -} - -// NewStore 创建新的 PostgreSQL Store 实例 -func NewStore(db *gorm.DB, logger *zap.Logger) *Store { - return &Store{ - db: db, - logger: logger, - User: NewUserStore(db), - Order: NewOrderStore(db), - } -} - -// DB 获取数据库连接 -func (s *Store) DB() *gorm.DB { - return s.db -} - -// Transaction 执行事务 -// 提供统一的事务管理接口，自动处理提交和回滚 -// 在事务内部，所有 Store 操作都会使用事务连接 -func (s *Store) Transaction(ctx context.Context, fn func(*Store) error) error { - return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error { - // 创建事务内的 Store 实例 - txStore := &Store{ - db: tx, - logger: s.logger, - User: NewUserStore(tx), - Order: NewOrderStore(tx), - } - return fn(txStore) - }) -} - -// WithContext 返回带上下文的数据库实例 -func (s *Store) WithContext(ctx context.Context) *gorm.DB { - return s.db.WithContext(ctx) -} diff --git a/internal/store/postgres/user_store.go b/internal/store/postgres/user_store.go deleted file mode 100644 index 0fc2b31..0000000 --- a/internal/store/postgres/user_store.go +++ /dev/null @@ -1,78 +0,0 @@ -package postgres - -import ( - "context" - - "github.com/break/junhong_cmp_fiber/internal/model" - "gorm.io/gorm" -) - -// UserStore 用户数据访问层 -type UserStore struct { - db *gorm.DB -} - -// NewUserStore 创建用户 Store -func NewUserStore(db *gorm.DB) *UserStore { - return &UserStore{db: db} -} - -// Create 创建用户 -func (s *UserStore) Create(ctx context.Context, user *model.User) error { - return s.db.WithContext(ctx).Create(user).Error -} - -// GetByID 根据 ID 获取用户 -func (s *UserStore) GetByID(ctx context.Context, id uint) (*model.User, error) { - var user model.User - err := s.db.WithContext(ctx).First(&user, id).Error - if err != nil { - return nil, err - } - return &user, nil -} - -// GetByUsername 根据用户名获取用户 -func (s *UserStore) GetByUsername(ctx context.Context, username string) (*model.User, error) { - var user model.User - err := s.db.WithContext(ctx).Where("username = ?", username).First(&user).Error - if err != nil { - return nil, err - } - return &user, nil -} - -// List 分页获取用户列表 -func (s *UserStore) List(ctx context.Context, page, pageSize int) ([]model.User, int64, error) { - var users []model.User - var total int64 - - // 计算总数 - if err := s.db.WithContext(ctx).Model(&model.User{}).Count(&total).Error; err != nil { - return nil, 0, err - } - - // 分页查询 - offset := (page - 1) * pageSize - err := s.db.WithContext(ctx). - Offset(offset). - Limit(pageSize). - Order("created_at DESC"). - Find(&users).Error - - if err != nil { - return nil, 0, err - } - - return users, total, nil -} - -// Update 更新用户 -func (s *UserStore) Update(ctx context.Context, user *model.User) error { - return s.db.WithContext(ctx).Save(user).Error -} - -// Delete 软删除用户 -func (s *UserStore) Delete(ctx context.Context, id uint) error { - return s.db.WithContext(ctx).Delete(&model.User{}, id).Error -} diff --git a/migrations/000001_init_schema.down.sql b/migrations/000001_init_schema.down.sql deleted file mode 100644 index 0b500a8..0000000 --- a/migrations/000001_init_schema.down.sql +++ /dev/null @@ -1,9 +0,0 @@ --- migrations/000001_init_schema.down.sql --- 回滚初始化 Schema --- 删除表和索引 - --- 删除订单表 -DROP TABLE IF EXISTS tb_order; - --- 删除用户表 -DROP TABLE IF EXISTS tb_user; diff --git a/migrations/000001_init_schema.up.sql b/migrations/000001_init_schema.up.sql deleted file mode 100644 index 873ab17..0000000 --- a/migrations/000001_init_schema.up.sql +++ /dev/null @@ -1,80 +0,0 @@ --- migrations/000001_init_schema.up.sql --- 初始化数据库 Schema --- 创建 tb_user 和 tb_order 表、索引 --- 注意: 表关系和 updated_at 更新在代码中处理 - --- 用户表 -CREATE TABLE IF NOT EXISTS tb_user ( - id SERIAL PRIMARY KEY, - created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, - updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, - deleted_at TIMESTAMP, - - -- 基本信息 - username VARCHAR(50) NOT NULL, - email VARCHAR(100) NOT NULL, - password VARCHAR(255) NOT NULL, - - -- 状态字段 - status VARCHAR(20) NOT NULL DEFAULT 'active', - - -- 元数据 - last_login_at TIMESTAMP, - - -- 唯一约束 - CONSTRAINT uk_user_username UNIQUE (username), - CONSTRAINT uk_user_email UNIQUE (email) -); - --- 用户表索引 -CREATE INDEX idx_user_deleted_at ON tb_user(deleted_at); -CREATE INDEX idx_user_status ON tb_user(status); -CREATE INDEX idx_user_created_at ON tb_user(created_at); - --- 订单表 -CREATE TABLE IF NOT EXISTS tb_order ( - id SERIAL PRIMARY KEY, - created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, - updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, - deleted_at TIMESTAMP, - - -- 业务唯一键 - order_id VARCHAR(50) NOT NULL, - - -- 关联关系 (注意: 无数据库外键约束，在代码中管理) - user_id INTEGER NOT NULL, - - -- 订单信息 - amount BIGINT NOT NULL, - status VARCHAR(20) NOT NULL DEFAULT 'pending', - remark VARCHAR(500), - - -- 时间字段 - paid_at TIMESTAMP, - completed_at TIMESTAMP, - - -- 唯一约束 - CONSTRAINT uk_order_order_id UNIQUE (order_id) -); - --- 订单表索引 -CREATE INDEX idx_order_deleted_at ON tb_order(deleted_at); -CREATE INDEX idx_order_user_id ON tb_order(user_id); -CREATE INDEX idx_order_status ON tb_order(status); -CREATE INDEX idx_order_created_at ON tb_order(created_at); -CREATE INDEX idx_order_order_id ON tb_order(order_id); - --- 添加注释 -COMMENT ON TABLE tb_user IS '用户表'; -COMMENT ON COLUMN tb_user.username IS '用户名（唯一）'; -COMMENT ON COLUMN tb_user.email IS '邮箱（唯一）'; -COMMENT ON COLUMN tb_user.password IS '密码（bcrypt 哈希）'; -COMMENT ON COLUMN tb_user.status IS '用户状态：active, inactive, suspended'; -COMMENT ON COLUMN tb_user.deleted_at IS '软删除时间'; - -COMMENT ON TABLE tb_order IS '订单表'; -COMMENT ON COLUMN tb_order.order_id IS '订单号（业务唯一键）'; -COMMENT ON COLUMN tb_order.user_id IS '用户 ID（在代码中维护关联，无数据库外键）'; -COMMENT ON COLUMN tb_order.amount IS '金额（分）'; -COMMENT ON COLUMN tb_order.status IS '订单状态：pending, paid, processing, completed, cancelled'; -COMMENT ON COLUMN tb_order.deleted_at IS '软删除时间'; diff --git a/openspec/AGENTS.md b/openspec/AGENTS.md new file mode 100644 index 0000000..f17db4f --- /dev/null +++ b/openspec/AGENTS.md @@ -0,0 +1,826 @@ +# OpenSpec Instructions + +Instructions for AI coding assistants using OpenSpec for spec-driven development. + +## TL;DR Quick Checklist + +- Search existing work: `openspec spec list --long`, `openspec list` (use `rg` only for full-text search) +- Decide scope: new capability vs modify existing capability +- Pick a unique `change-id`: kebab-case, verb-led (`add-`, `update-`, `remove-`, `refactor-`) +- Scaffold: `proposal.md`, `tasks.md`, `design.md` (only if needed), and delta specs per affected capability +- Write deltas: use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`; include at least one `#### Scenario:` per requirement +- Validate: `openspec validate [change-id] --strict` and fix issues +- Request approval: Do not start implementation until proposal is approved + +## Three-Stage Workflow + +### Stage 1: Creating Changes +Create proposal when you need to: +- Add features or functionality +- Make breaking changes (API, schema) +- Change architecture or patterns +- Optimize performance (changes behavior) +- Update security patterns + +Triggers (examples): +- "Help me create a change proposal" +- "Help me plan a change" +- "Help me create a proposal" +- "I want to create a spec proposal" +- "I want to create a spec" + +Loose matching guidance: +- Contains one of: `proposal`, `change`, `spec` +- With one of: `create`, `plan`, `make`, `start`, `help` + +Skip proposal for: +- Bug fixes (restore intended behavior) +- Typos, formatting, comments +- Dependency updates (non-breaking) +- Configuration changes +- Tests for existing behavior + +**Workflow** +1. Review `openspec/project.md`, `openspec list`, and `openspec list --specs` to understand current context. +2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas under `openspec/changes//`. +3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement. +4. Run `openspec validate --strict` and resolve any issues before sharing the proposal. + +### Stage 2: Implementing Changes +Track these steps as TODOs and complete them one by one. +1. **Read proposal.md** - Understand what's being built +2. **Read design.md** (if exists) - Review technical decisions +3. **Read tasks.md** - Get implementation checklist +4. **Implement tasks sequentially** - Complete in order +5. **Confirm completion** - Ensure every item in `tasks.md` is finished before updating statuses +6. **Update checklist** - After all work is done, set every task to `- [x]` so the list reflects reality +7. **Approval gate** - Do not start implementation until the proposal is reviewed and approved + +### Stage 3: Archiving Changes +After deployment, create separate PR to: +- Move `changes/[name]/` → `changes/archive/YYYY-MM-DD-[name]/` +- Update `specs/` if capabilities changed +- Use `openspec archive --skip-specs --yes` for tooling-only changes (always pass the change ID explicitly) +- Run `openspec validate --strict` to confirm the archived change passes checks + +## Before Any Task + +**Context Checklist:** +- [ ] Read relevant specs in `specs/[capability]/spec.md` +- [ ] Check pending changes in `changes/` for conflicts +- [ ] Read `openspec/project.md` for conventions +- [ ] Run `openspec list` to see active changes +- [ ] Run `openspec list --specs` to see existing capabilities + +**Before Creating Specs:** +- Always check if capability already exists +- Prefer modifying existing specs over creating duplicates +- Use `openspec show [spec]` to review current state +- If request is ambiguous, ask 1–2 clarifying questions before scaffolding + +### Search Guidance +- Enumerate specs: `openspec spec list --long` (or `--json` for scripts) +- Enumerate changes: `openspec list` (or `openspec change list --json` - deprecated but available) +- Show details: + - Spec: `openspec show --type spec` (use `--json` for filters) + - Change: `openspec show --json --deltas-only` +- Full-text search (use ripgrep): `rg -n "Requirement:|Scenario:" openspec/specs` + +## Quick Start + +### CLI Commands + +```bash +# Essential commands +openspec list # List active changes +openspec list --specs # List specifications +openspec show [item] # Display change or spec +openspec validate [item] # Validate changes or specs +openspec archive [--yes|-y] # Archive after deployment (add --yes for non-interactive runs) + +# Project management +openspec init [path] # Initialize OpenSpec +openspec update [path] # Update instruction files + +# Interactive mode +openspec show # Prompts for selection +openspec validate # Bulk validation mode + +# Debugging +openspec show [change] --json --deltas-only +openspec validate [change] --strict +``` + +### Command Flags + +- `--json` - Machine-readable output +- `--type change|spec` - Disambiguate items +- `--strict` - Comprehensive validation +- `--no-interactive` - Disable prompts +- `--skip-specs` - Archive without spec updates +- `--yes`/`-y` - Skip confirmation prompts (non-interactive archive) + +## Directory Structure + +``` +openspec/ +├── project.md # Project conventions +├── specs/ # Current truth - what IS built +│ └── [capability]/ # Single focused capability +│ ├── spec.md # Requirements and scenarios +│ └── design.md # Technical patterns +├── changes/ # Proposals - what SHOULD change +│ ├── [change-name]/ +│ │ ├── proposal.md # Why, what, impact +│ │ ├── tasks.md # Implementation checklist +│ │ ├── design.md # Technical decisions (optional; see criteria) +│ │ └── specs/ # Delta changes +│ │ └── [capability]/ +│ │ └── spec.md # ADDED/MODIFIED/REMOVED +│ └── archive/ # Completed changes +``` + +## Creating Change Proposals + +### Decision Tree + +``` +New request? +├─ Bug fix restoring spec behavior? → Fix directly +├─ Typo/format/comment? → Fix directly +├─ New feature/capability? → Create proposal +├─ Breaking change? → Create proposal +├─ Architecture change? → Create proposal +└─ Unclear? → Create proposal (safer) +``` + +### Proposal Structure + +1. **Create directory:** `changes/[change-id]/` (kebab-case, verb-led, unique) + +2. **Write proposal.md:** +```markdown +## Why +[1-2 sentences on problem/opportunity] + +## What Changes +- [Bullet list of changes] +- [Mark breaking changes with **BREAKING**] + +## Impact +- Affected specs: [list capabilities] +- Affected code: [key files/systems] +``` + +3. **Create spec deltas:** `specs/[capability]/spec.md` +```markdown +## ADDED Requirements +### Requirement: New Feature +The system SHALL provide... + +#### Scenario: Success case +- **WHEN** user performs action +- **THEN** expected result + +## MODIFIED Requirements +### Requirement: Existing Feature +[Complete modified requirement] + +## REMOVED Requirements +### Requirement: Old Feature +**Reason**: [Why removing] +**Migration**: [How to handle] +``` +If multiple capabilities are affected, create multiple delta files under `changes/[change-id]/specs//spec.md`—one per capability. + +4. **Create tasks.md:** +```markdown +## 1. Implementation +- [ ] 1.1 Create database schema +- [ ] 1.2 Implement API endpoint +- [ ] 1.3 Add frontend component +- [ ] 1.4 Write tests +``` + +5. **Create design.md when needed:** +Create `design.md` if any of the following apply; otherwise omit it: +- Cross-cutting change (multiple services/modules) or a new architectural pattern +- New external dependency or significant data model changes +- Security, performance, or migration complexity +- Ambiguity that benefits from technical decisions before coding + +Minimal `design.md` skeleton: +```markdown +## Context +[Background, constraints, stakeholders] + +## Goals / Non-Goals +- Goals: [...] +- Non-Goals: [...] + +## Decisions +- Decision: [What and why] +- Alternatives considered: [Options + rationale] + +## Risks / Trade-offs +- [Risk] → Mitigation + +## Migration Plan +[Steps, rollback] + +## Open Questions +- [...] +``` + +## Spec File Format + +### Critical: Scenario Formatting + +**CORRECT** (use #### headers): +```markdown +#### Scenario: User login success +- **WHEN** valid credentials provided +- **THEN** return JWT token +``` + +**WRONG** (don't use bullets or bold): +```markdown +- **Scenario: User login** ❌ +**Scenario**: User login ❌ +### Scenario: User login ❌ +``` + +Every requirement MUST have at least one scenario. + +### Requirement Wording +- Use SHALL/MUST for normative requirements (avoid should/may unless intentionally non-normative) + +### Delta Operations + +- `## ADDED Requirements` - New capabilities +- `## MODIFIED Requirements` - Changed behavior +- `## REMOVED Requirements` - Deprecated features +- `## RENAMED Requirements` - Name changes + +Headers matched with `trim(header)` - whitespace ignored. + +#### When to use ADDED vs MODIFIED +- ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding "Slash Command Configuration") rather than altering the semantics of an existing requirement. +- MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details. +- RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name. + +Common pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren’t explicitly changing the existing requirement, add a new requirement under ADDED instead. + +Authoring a MODIFIED requirement correctly: +1) Locate the existing requirement in `openspec/specs//spec.md`. +2) Copy the entire requirement block (from `### Requirement: ...` through its scenarios). +3) Paste it under `## MODIFIED Requirements` and edit to reflect the new behavior. +4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one `#### Scenario:`. + +Example for RENAMED: +```markdown +## RENAMED Requirements +- FROM: `### Requirement: Login` +- TO: `### Requirement: User Authentication` +``` + +## Troubleshooting + +### Common Errors + +**"Change must have at least one delta"** +- Check `changes/[name]/specs/` exists with .md files +- Verify files have operation prefixes (## ADDED Requirements) + +**"Requirement must have at least one scenario"** +- Check scenarios use `#### Scenario:` format (4 hashtags) +- Don't use bullet points or bold for scenario headers + +**Silent scenario parsing failures** +- Exact format required: `#### Scenario: Name` +- Debug with: `openspec show [change] --json --deltas-only` + +### Validation Tips + +```bash +# Always use strict mode for comprehensive checks +openspec validate [change] --strict + +# Debug delta parsing +openspec show [change] --json | jq '.deltas' + +# Check specific requirement +openspec show [spec] --json -r 1 +``` + +## Happy Path Script + +```bash +# 1) Explore current state +openspec spec list --long +openspec list +# Optional full-text search: +# rg -n "Requirement:|Scenario:" openspec/specs +# rg -n "^#|Requirement:" openspec/changes + +# 2) Choose change id and scaffold +CHANGE=add-two-factor-auth +mkdir -p openspec/changes/$CHANGE/{specs/auth} +printf "## Why\n...\n\n## What Changes\n- ...\n\n## Impact\n- ...\n" > openspec/changes/$CHANGE/proposal.md +printf "## 1. Implementation\n- [ ] 1.1 ...\n" > openspec/changes/$CHANGE/tasks.md + +# 3) Add deltas (example) +cat > openspec/changes/$CHANGE/specs/auth/spec.md << 'EOF' +## ADDED Requirements +### Requirement: Two-Factor Authentication +Users MUST provide a second factor during login. + +#### Scenario: OTP required +- **WHEN** valid credentials are provided +- **THEN** an OTP challenge is required +EOF + +# 4) Validate +openspec validate $CHANGE --strict +``` + +## Multi-Capability Example + +``` +openspec/changes/add-2fa-notify/ +├── proposal.md +├── tasks.md +└── specs/ + ├── auth/ + │ └── spec.md # ADDED: Two-Factor Authentication + └── notifications/ + └── spec.md # ADDED: OTP email notification +``` + +auth/spec.md +```markdown +## ADDED Requirements +### Requirement: Two-Factor Authentication +... +``` + +notifications/spec.md +```markdown +## ADDED Requirements +### Requirement: OTP Email Notification +... +``` + +## Best Practices + +### Simplicity First +- Default to <100 lines of new code +- Single-file implementations until proven insufficient +- Avoid frameworks without clear justification +- Choose boring, proven patterns + +### Complexity Triggers +Only add complexity with: +- Performance data showing current solution too slow +- Concrete scale requirements (>1000 users, >100MB data) +- Multiple proven use cases requiring abstraction + +### Clear References +- Use `file.ts:42` format for code locations +- Reference specs as `specs/auth/spec.md` +- Link related changes and PRs + +### Capability Naming +- Use verb-noun: `user-auth`, `payment-capture` +- Single purpose per capability +- 10-minute understandability rule +- Split if description needs "AND" + +### Change ID Naming +- Use kebab-case, short and descriptive: `add-two-factor-auth` +- Prefer verb-led prefixes: `add-`, `update-`, `remove-`, `refactor-` +- Ensure uniqueness; if taken, append `-2`, `-3`, etc. + +## Tool Selection Guide + +| Task | Tool | Why | +|------|------|-----| +| Find files by pattern | Glob | Fast pattern matching | +| Search code content | Grep | Optimized regex search | +| Read specific files | Read | Direct file access | +| Explore unknown scope | Task | Multi-step investigation | + +## Error Recovery + +### Change Conflicts +1. Run `openspec list` to see active changes +2. Check for overlapping specs +3. Coordinate with change owners +4. Consider combining proposals + +### Validation Failures +1. Run with `--strict` flag +2. Check JSON output for details +3. Verify spec file format +4. Ensure scenarios properly formatted + +### Missing Context +1. Read project.md first +2. Check related specs +3. Review recent archives +4. Ask for clarification + +## Quick Reference + +### Stage Indicators +- `changes/` - Proposed, not yet built +- `specs/` - Built and deployed +- `archive/` - Completed changes + +### File Purposes +- `proposal.md` - Why and what +- `tasks.md` - Implementation steps +- `design.md` - Technical decisions +- `spec.md` - Requirements and behavior + +### CLI Essentials +```bash +openspec list # What's in progress? +openspec show [item] # View details +openspec validate --strict # Is it correct? +openspec archive [--yes|-y] # Mark complete (add --yes for automation) +``` + +Remember: Specs are truth. Changes are proposals. Keep them in sync. + +--- + +# Project-Specific Development Guidelines + +以下是本项目的开发规范，所有 AI 助手在创建提案和实现代码时必须遵守。 + +## 语言要求 + +**必须遵守:** +- 永远用中文交互 +- 注释必须使用中文 +- 文档必须使用中文 +- 日志消息必须使用中文 +- 用户可见的错误消息必须使用中文 +- 变量名、函数名、类型名必须使用英文（遵循 Go 命名规范） +- Go 文档注释（doc comments for exported APIs）可以使用英文以保持生态兼容性，但中文注释更佳 + +## 核心开发原则 + +### 技术栈遵守 + +**必须遵守 (MUST):** + +- 开发时严格遵守项目定义的技术栈：Fiber + GORM + Viper + Zap + Lumberjack.v2 + Validator + sonic JSON + Asynq + PostgreSQL +- 禁止使用原生调用或绕过框架的快捷方式（禁止 `database/sql` 直接调用、禁止 `net/http` 替代 Fiber、禁止 `encoding/json` 替代 sonic） +- 所有 HTTP 路由和中间件必须使用 Fiber 框架 +- 所有数据库操作必须通过 GORM 进行 +- 所有配置管理必须使用 Viper +- 所有日志记录必须使用 Zap + Lumberjack.v2 +- 所有 JSON 序列化优先使用 sonic，仅在必须使用标准库的场景才使用 `encoding/json` +- 所有异步任务必须使用 Asynq +- 必须使用 Go 官方工具链：`go fmt`、`go vet`、`golangci-lint` +- 必须使用 Go Modules 进行依赖管理 + +**理由:** + +一致的技术栈使用确保代码可维护性、团队协作效率和长期技术债务可控。绕过框架的"快捷方式"会导致代码碎片化、难以调试、性能不一致和安全漏洞。 + +### 代码质量标准 + +**架构分层:** + +- 代码必须遵循项目分层架构：`Handler → Service → Store → Model` +- Handler 层只能处理 HTTP 请求/响应，不得包含业务逻辑 +- Service 层包含所有业务逻辑，支持跨模块调用 +- Store 层统一管理所有数据访问，支持事务处理 +- Model 层定义清晰的数据结构和 DTO +- 所有依赖通过结构体字段进行依赖注入（不使用构造函数模式） + +**错误和响应处理:** + +- 所有公共错误必须在 `pkg/errors/` 中定义，使用统一错误码 +- 所有 API 响应必须使用 `pkg/response/` 的统一格式 +- 所有常量必须在 `pkg/constants/` 中定义和管理 +- 所有 Redis key 必须通过 `pkg/constants/` 中的 Key 生成函数统一管理 + +**代码注释和文档:** + +- 必须为所有导出的函数、类型和常量编写 Go 风格的文档注释（`// FunctionName does something...`） +- 代码注释（implementation comments）应该使用中文 +- 日志消息应该使用中文 +- 用户可见的错误消息必须使用中文（通过 `pkg/errors/` 的双语消息支持） +- Go 文档注释（doc comments for exported APIs）可以使用英文以保持生态兼容性，但中文注释更佳 +- 变量名、函数名、类型名必须使用英文（遵循 Go 命名规范） + +**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`（不是 `users`、`userService`、`user_service`） +- 接口命名应该使用 `-er` 后缀：`Reader`、`Writer`、`Logger`（不是 `ILogger`、`LoggerInterface`） + +**常量管理规范:** + +- 业务常量（状态码、类型枚举等）必须定义在 `pkg/constants/constants.go` 或按模块分文件 +- Redis key 必须使用函数生成，不允许硬编码字符串拼接 +- Redis key 生成函数必须遵循命名规范：`Redis{Module}{Purpose}Key(params...)` +- Redis key 格式必须使用冒号分隔：`{module}:{purpose}:{identifier}` +- 禁止在代码中直接使用 magic numbers（未定义含义的数字字面量） +- 禁止在代码中硬编码字符串字面量（URL、状态码、配置值、业务规则等） +- 当相同的字面量值在 3 个或以上位置使用时，必须提取为常量 +- 已定义的常量必须被使用，禁止重复硬编码相同的值 + +**函数复杂度和职责分离:** + +- 函数长度不得超过合理范围（通常 50-100 行，核心逻辑建议 ≤ 50 行） +- 超过 100 行的函数必须拆分为多个小函数，每个函数只负责一件事 +- `main()` 函数只做编排（orchestration），不包含具体实现逻辑 +- `main()` 函数中的每个初始化步骤应该提取为独立的辅助函数 +- 编排函数必须清晰表达流程，避免嵌套的实现细节 +- 必须遵循单一职责原则（Single Responsibility Principle） + +## Go 语言惯用设计原则 + +**核心理念：写 Go 味道的代码，不要写 Java 味道的代码** + +**包组织:** + +- 包结构必须扁平化，避免深层嵌套（最多 2-3 层） +- 包必须按功能组织，不是按层次组织 +- 包名必须描述功能，不是类型（`http` 不是 `httputils`、`handlers`） + +推荐的 Go 风格结构: +``` +internal/ +├── user/ # user 功能的所有代码 +│ ├── handler.go # HTTP handlers +│ ├── service.go # 业务逻辑 +│ ├── store.go # 数据访问 +│ └── model.go # 数据模型 +├── order/ +└── sim/ +``` + +**接口设计:** + +- 接口必须小而专注（1-3 个方法），不是大而全 +- 接口应该在使用方定义，不是实现方（依赖倒置） +- 接口命名应该使用 `-er` 后缀：`Reader`、`Writer`、`Storer` +- 禁止使用 `I` 前缀或 `Interface` 后缀 +- 禁止创建只有一个实现的接口（除非明确需要抽象） + +**错误处理:** + +- 错误必须显式返回和检查，不使用异常（panic/recover） +- 错误处理必须紧跟错误产生的代码 +- 必须使用 `errors.Is()` 和 `errors.As()` 检查错误类型 +- 必须使用 `fmt.Errorf()` 包装错误，保留错误链 +- 自定义错误应该实现 `error` 接口 +- panic 只能用于不可恢复的程序错误 + +**结构体和方法:** + +- 结构体必须简单直接，不是类（class）的替代品 +- 禁止为每个字段创建 getter/setter 方法 +- 必须直接访问导出的字段（大写开头） +- 必须使用组合（composition）而不是继承（inheritance） +- 构造函数应该命名为 `New` 或 `NewXxx`，返回具体类型 +- 禁止使用构造器模式（Builder Pattern）除非真正需要 + +**并发模式:** + +- 必须使用 goroutines 和 channels，不是线程和锁（大多数情况） +- 必须使用 `context.Context` 传递取消信号 +- 必须遵循"通过通信共享内存，不要通过共享内存通信" +- 应该使用 `sync.WaitGroup` 等待 goroutines 完成 +- 应该使用 `sync.Once` 确保只执行一次 +- 禁止创建线程池类（Go 运行时已处理） + +**命名约定:** + +- 变量名必须简短且符合上下文（短作用域用短名字：`i`, `j`, `k`；长作用域用描述性名字） +- 缩写词必须保持一致的大小写：`URL`, `HTTP`, `ID`（不是 `Url`, `Http`, `Id`） +- 禁止使用匈牙利命名法或类型前缀：`strName`, `arrUsers` +- 禁止使用下划线连接（除了测试和包名） +- 方法接收者名称应该使用 1-2 个字母的缩写，全文件保持一致 + +**严格禁止的 Java 风格模式:** + +1. ❌ 过度抽象（不需要的接口、工厂、构造器） +2. ❌ Getter/Setter（直接访问导出字段） +3. ❌ 继承层次（使用组合，不是嵌入） +4. ❌ 异常处理（使用错误返回，不是 panic/recover） +5. ❌ 单例模式（使用包级别变量或 `sync.Once`） +6. ❌ 线程池（直接使用 goroutines） +7. ❌ 深层包嵌套（保持扁平结构） +8. ❌ 类型前缀（`IService`, `AbstractBase`, `ServiceImpl`） +9. ❌ Bean 风格（不需要 POJO/JavaBean 模式） +10. ❌ 过度 DI 框架（简单直接的依赖注入） + +## 测试标准 + +**测试要求:** + +- 所有核心业务逻辑（Service 层）必须有单元测试覆盖 +- 所有 API 端点必须有集成测试覆盖 +- 所有数据库操作应该有事务回滚测试 +- 测试必须使用 Go 标准测试框架（`testing` 包） +- 测试文件必须与源文件同目录，命名为 `*_test.go` +- 测试函数必须使用 `Test` 前缀：`func TestUserCreate(t *testing.T)` +- 基准测试必须使用 `Benchmark` 前缀：`func BenchmarkUserCreate(b *testing.B)` + +**测试性能要求:** + +- 测试必须可独立运行，不依赖外部服务（使用 mock 或 testcontainers） +- 单元测试必须在 100ms 内完成 +- 集成测试应该在 1s 内完成 +- 测试覆盖率应该达到 70% 以上（核心业务代码必须 90% 以上） + +**测试最佳实践:** + +- 测试必须使用 table-driven tests 处理多个测试用例 +- 测试必须使用 `t.Helper()` 标记辅助函数 + +## 数据库设计原则 + +**核心规则:** + +- 数据库表之间禁止建立外键约束（Foreign Key Constraints） +- GORM 模型之间禁止使用 ORM 关联关系（`foreignKey`、`references`、`hasMany`、`belongsTo` 等标签） +- 表之间的关联必须通过存储关联 ID 字段手动维护 +- 关联数据查询必须在代码层面显式执行，不依赖 ORM 的自动加载或预加载 +- 模型结构体只能包含简单字段，不应包含其他模型的嵌套引用 +- 数据库迁移脚本禁止包含外键约束定义 +- 数据库迁移脚本禁止包含触发器用于维护关联数据 +- 时间字段（`created_at`、`updated_at`）的更新必须由 GORM 自动处理，不使用数据库触发器 + +**设计理由:** + +1. **灵活性**：业务逻辑完全在代码中控制，不受数据库约束限制 +2. **性能**：无外键约束意味着无数据库层面的引用完整性检查开销 +3. **简单直接**：显式的关联数据查询使数据流向清晰可见 +4. **可控性**：开发者完全掌控何时查询关联数据、查询哪些关联数据 +5. **可维护性**：数据库 schema 更简单，迁移更容易 +6. **分布式友好**：在微服务和分布式数据库场景下更容易扩展 + +## API 设计规范 + +**统一响应格式:** + +所有 API 响应必须使用统一的 JSON 格式： +```json +{ + "code": 0, + "message": "success", + "data": {}, + "timestamp": "2025-11-10T15:30:00Z" +} +``` + +**API 设计要求:** + +- 所有错误响应必须包含明确的错误码和错误消息（中英文双语） +- 所有 API 端点必须遵循 RESTful 设计原则 +- 所有分页 API 必须使用统一的分页参数：`page`、`page_size`、`total` +- 所有时间字段必须使用 ISO 8601 格式（RFC3339） +- 所有货币金额必须使用整数表示（分为单位），避免浮点精度问题 +- 所有布尔字段必须使用 `true`/`false`，不使用 `0`/`1` +- API 版本必须通过 URL 路径管理（如 `/api/v1/...`） + +## 错误处理规范 + +**统一错误处理:** + +- 所有 API 错误响应必须使用统一的 JSON 格式（通过 `pkg/errors/` 全局 ErrorHandler） +- 所有 Handler 层错误必须通过返回 `error` 传递给全局 ErrorHandler，禁止手动构造错误响应 +- 所有业务错误必须使用 `pkg/errors.New()` 或 `pkg/errors.Wrap()` 创建 `AppError`，并指定错误码 +- 所有错误码必须在 `pkg/errors/codes.go` 中统一定义和管理 + +**Panic 处理:** + +- 所有 Panic 必须被 Recover 中间件自动捕获，转换为 500 错误响应 +- 禁止在业务代码中主动 `panic`（除非遇到不可恢复的编程错误） +- 禁止在 Handler 中直接使用 `c.Status().JSON()` 返回错误响应 + +**错误日志:** + +- 所有错误日志必须包含完整的请求上下文（Request ID、路径、方法、参数等） +- 5xx 服务端错误必须自动脱敏，只返回通用错误消息，原始错误仅记录到日志 +- 4xx 客户端错误可以返回具体业务错误消息（如"用户名已存在"） + +**错误码分类:** + +- `0`: 成功 +- `1000-1999`: 客户端错误（4xx HTTP 状态码，日志级别 Warn） +- `2000-2999`: 服务端错误（5xx HTTP 状态码，日志级别 Error） + +## 访问日志规范 + +**核心要求:** + +- 所有 HTTP 请求必须被记录到 `access.log`，无例外 +- 访问日志必须记录完整的请求参数（query 参数 + request body） +- 访问日志必须记录完整的响应参数（response body） +- 请求/响应 body 必须限制大小为 50KB，超过部分截断并标注 `... (truncated)` +- 访问日志必须通过统一的 Logger 中间件（`pkg/logger/Middleware()`）记录 +- 任何中间件的短路返回（认证失败、限流拒绝、参数验证失败等）禁止绕过访问日志 + +**必需字段:** + +访问日志必须包含以下字段： +- `method`: HTTP 方法 +- `path`: 请求路径 +- `query`: Query 参数字符串 +- `status`: HTTP 状态码 +- `duration_ms`: 请求耗时（毫秒） +- `request_id`: 请求唯一 ID +- `ip`: 客户端 IP +- `user_agent`: 用户代理 +- `user_id`: 用户 ID（认证后有值，否则为空） +- `request_body`: 请求体（限制 50KB） +- `response_body`: 响应体（限制 50KB） + +**日志配置:** + +- 访问日志应该使用 JSON 格式，便于日志分析和监控 +- 访问日志文件必须配置自动轮转（基于大小或时间） + +## 性能要求 + +**性能指标:** + +- API 响应时间（P95）必须 < 200ms（数据库查询 < 50ms） +- API 响应时间（P99）必须 < 500ms +- 批量操作必须使用批量查询/插入，避免 N+1 查询问题 +- 所有数据库查询必须有适当的索引支持 +- 列表查询必须实现分页，默认 `page_size=20`，最大 `page_size=100` +- 异步任务必须用于非实时操作（批量同步、分佣计算等） + +**资源限制:** + +- 内存使用（API 服务）应该 < 500MB（正常负载） +- 内存使用（Worker 服务）应该 < 1GB（正常负载） +- 数据库连接池必须配置合理（`MaxOpenConns=25`, `MaxIdleConns=10`, `ConnMaxLifetime=5m`） +- Redis 连接池必须配置合理（`PoolSize=10`, `MinIdleConns=5`） + +**并发处理:** + +- 并发操作应该使用 goroutines 和 channels（不是线程池模式） +- 必须使用 `context.Context` 进行超时和取消控制 +- 必须使用 `sync.Pool` 复用频繁分配的对象（如缓冲区） + +## 文档规范 + +**文档结构要求:** + +- 每个功能完成后必须在 `docs/` 目录创建总结文档 +- 总结文档路径必须遵循规范：`docs/{feature-id}/` 对应 `specs/{feature-id}/` +- 总结文档文件名必须使用中文命名（例如：`功能总结.md`、`使用指南.md`、`架构说明.md`） +- 总结文档内容必须使用中文编写 +- 每次添加新功能总结文档时必须同步更新 `README.md` + +**README.md 更新要求:** + +- README.md 中的功能描述必须简短精炼，让首次接触项目的开发者能快速了解 +- README.md 的功能描述应该控制在 2-3 句话以内 +- 使用中文，便于中文开发者快速理解 +- 提供到详细文档的链接 +- 按功能模块分组（如"核心功能"、"中间件"、"业务模块"等） + +--- + +## 提案创建检查清单 + +在创建 OpenSpec 提案时，请确保： + +1. ✅ **技术栈合规**: 提案中的技术选型必须符合项目技术栈要求 +2. ✅ **架构分层**: 设计必须遵循 Handler → Service → Store → Model 分层 +3. ✅ **错误处理**: 错误处理方案必须使用统一的 `pkg/errors/` 系统 +4. ✅ **常量管理**: 新增常量必须定义在 `pkg/constants/` +5. ✅ **Go 风格**: 代码设计必须遵循 Go 惯用法，避免 Java 风格 +6. ✅ **测试要求**: 提案必须包含测试计划（单元测试 + 集成测试） +7. ✅ **性能考虑**: 需要考虑性能指标和资源限制 +8. ✅ **文档计划**: 提案必须包含文档更新计划 +9. ✅ **中文优先**: 所有文档、注释、日志必须使用中文 + +## 实现检查清单 + +在实现 OpenSpec 提案时，请确保： + +1. ✅ **代码格式**: 所有代码已通过 `gofmt` 格式化 +2. ✅ **代码检查**: 所有代码已通过 `go vet` 和 `golangci-lint` 检查 +3. ✅ **测试覆盖**: 核心业务逻辑测试覆盖率 ≥ 90% +4. ✅ **性能测试**: API 响应时间符合性能指标要求 +5. ✅ **错误处理**: 所有错误已正确处理和记录 +6. ✅ **文档更新**: README.md 和功能文档已更新 +7. ✅ **迁移脚本**: 数据库变更已创建迁移脚本 +8. ✅ **日志记录**: 关键操作已添加访问日志和业务日志 +9. ✅ **代码审查**: 代码已通过团队审查 diff --git a/openspec/changes/refactor-framework-cleanup/design.md b/openspec/changes/refactor-framework-cleanup/design.md new file mode 100644 index 0000000..de0effa --- /dev/null +++ b/openspec/changes/refactor-framework-cleanup/design.md @@ -0,0 +1,422 @@ +## Context + +当前项目处于框架搭建阶段，存在多处技术债务需要清理： +- 两套 Auth 实现产生于不同开发阶段，未整合 +- 示例代码（user/order）是早期测试用途，现已有真实 RBAC 代码 +- pkg/errors 和 pkg/response 设计时职责划分不清晰 +- DataPermissionScope 实现完整但从未集成使用 + +**约束条件**： +- 必须保持 Go 惯用模式，避免 Java 风格过度抽象 +- main.go 在未来开发中应该不需要修改 +- 数据权限过滤必须支持绕过机制 + +## Goals / Non-Goals + +### Goals +- 清理所有示例和重复代码，使框架干净整洁 +- 统一认证、错误处理、响应格式的实现方式 +- 实现数据权限的 GORM 自动化过滤 +- 将组件初始化从 main.go 解耦，支持未来扩展 +- 在关键扩展点添加 TODO 标记 + +### Non-Goals +- 不实现完整的 DI 框架（保持 Go 简洁风格） +- 不实现自动注册机制（使用显式工厂模式） +- 不重构现有 RBAC 业务逻辑 +- 不添加新的业务功能 + +## Decisions + +### Decision 1: Auth 中间件合并策略 + +**选择**：重新设计合并版本 + +**实现方案**： +```go +// pkg/middleware/auth.go - 合并版本 +type AuthConfig struct { + TokenExtractor func(*fiber.Ctx) string // 自定义 token 提取 + SkipPaths []string // 跳过认证的路径 + Validator func(string) (*UserInfo, error) // token 验证函数 +} + +func Auth(cfg AuthConfig) fiber.Handler { + return func(c *fiber.Ctx) error { + // 1. 检查跳过路径 + // 2. 提取 token + // 3. 验证 token + // 4. 设置用户上下文（同时设置 Locals 和 Context） + // 5. 错误统一返回 AppError，由全局 ErrorHandler 处理 + } +} +``` + +**理由**： +- 合并两者优点：pkg 版本的可配置性 + internal 版本的统一错误格式 +- 统一使用 `return errors.New()` 让全局 ErrorHandler 处理 +- 消除错误格式不一致问题 + +### Decision 2: 组件注册解耦策略 + +**选择**：Bootstrap 包 + 按模块拆分 + 工厂函数模式 + +**实现方案**： +``` +internal/bootstrap/ +├── bootstrap.go # 主入口，编排初始化流程 +├── dependencies.go # Dependencies 结构体定义 +├── stores.go # 所有 Store 初始化逻辑 +├── services.go # 所有 Service 初始化逻辑 +├── handlers.go # 所有 Handler 初始化逻辑 +└── types.go # Handlers 结构体定义 +``` + +**bootstrap.go** - 主入口编排： +```go +// Bootstrap 初始化所有组件并返回 Handlers +func Bootstrap(deps *Dependencies) (*Handlers, error) { + // 1. 初始化 GORM Callback（必须在 Store 之前） + if err := registerGORMCallbacks(deps.DB); err != nil { + return nil, err + } + + // 2. 初始化 Stores + stores := initStores(deps) + + // 3. 初始化 Services + services := initServices(stores) + + // 4. 初始化 Handlers + handlers := initHandlers(services) + + return handlers, nil +} +``` + +**stores.go** - Store 层初始化： +```go +type Stores struct { + Account *postgres.AccountStore + Role *postgres.RoleStore + Permission *postgres.PermissionStore + AccountRole *postgres.AccountRoleStore + RolePermission *postgres.RolePermissionStore + // TODO: 新增 Store 在此添加字段 +} + +func initStores(deps *Dependencies) *Stores { + return &Stores{ + Account: postgres.NewAccountStore(deps.DB, deps.Redis), + Role: postgres.NewRoleStore(deps.DB), + Permission: postgres.NewPermissionStore(deps.DB), + AccountRole: postgres.NewAccountRoleStore(deps.DB), + RolePermission: postgres.NewRolePermissionStore(deps.DB), + // TODO: 新增 Store 在此初始化 + } +} +``` + +**services.go** - Service 层初始化： +```go +type Services struct { + Account *accountSvc.Service + Role *roleSvc.Service + Permission *permissionSvc.Service + // TODO: 新增 Service 在此添加字段 +} + +func initServices(stores *Stores) *Services { + return &Services{ + Account: accountSvc.New(stores.Account, stores.Role, stores.AccountRole), + Role: roleSvc.New(stores.Role, stores.Permission, stores.RolePermission), + Permission: permissionSvc.New(stores.Permission), + // TODO: 新增 Service 在此初始化 + } +} +``` + +**handlers.go** - Handler 层初始化： +```go +func initHandlers(services *Services) *Handlers { + return &Handlers{ + Account: handler.NewAccountHandler(services.Account), + Role: handler.NewRoleHandler(services.Role), + Permission: handler.NewPermissionHandler(services.Permission), + // TODO: 新增 Handler 在此初始化 + } +} +``` + +**types.go** - 类型定义： +```go +// Handlers 封装所有 HTTP 处理器 +type Handlers struct { + Account *handler.AccountHandler + Role *handler.RoleHandler + Permission *handler.PermissionHandler + // TODO: 新增 Handler 在此添加字段 +} +``` + +**dependencies.go** - 基础依赖： +```go +// Dependencies 封装所有基础依赖 +type Dependencies struct { + DB *gorm.DB + Redis *redis.Client + Logger *zap.Logger +} +``` + +**main.go 简化后**： +```go +func main() { + // 初始化基础依赖 + deps := initDependencies() + + // 一行完成所有业务组件初始化 + handlers, err := bootstrap.Bootstrap(deps) + + // 设置路由 + routes.Setup(app, handlers) + + // 启动服务 + app.Listen(":8080") +} +``` + +**理由**： +- **按层次拆分**：stores.go、services.go、handlers.go 职责清晰 +- **易于扩展**：每层只需在对应文件中添加初始化代码 +- **文件大小可控**：每个文件 < 100 行，避免单文件臃肿 +- **main.go 零修改**：新增业务只修改 bootstrap 内部文件 +- **符合 Go 风格**：显式依赖注入，不使用复杂的 DI 框架 +- **TODO 标记清晰**：每层都有明确的扩展点标记 + +### Decision 3: 数据权限 GORM Callback 实现 + +**选择**：GORM Callback 自动化 + Context 绕过机制 + +**实现方案**： +```go +// pkg/gorm/callback.go + +type contextKey string +const SkipDataPermissionKey contextKey = "skip_data_permission" + +// SkipDataPermission 返回跳过数据权限过滤的 Context +func SkipDataPermission(ctx context.Context) context.Context { + return context.WithValue(ctx, SkipDataPermissionKey, true) +} + +// RegisterDataPermissionCallback 注册 GORM Callback +func RegisterDataPermissionCallback(db *gorm.DB, accountStore AccountStoreInterface) { + db.Callback().Query().Before("gorm:query").Register("data_permission", func(tx *gorm.DB) { + ctx := tx.Statement.Context + + // 检查是否跳过 + if skip, ok := ctx.Value(SkipDataPermissionKey).(bool); ok && skip { + return + } + + // 检查 root 用户 + if middleware.IsRootUser(ctx) { + return + } + + // 获取用户下级 ID 并应用过滤 + userID := middleware.GetUserIDFromContext(ctx) + subordinateIDs, _ := accountStore.GetSubordinateIDs(ctx, userID) + + // 只对包含 owner_id 字段的表应用过滤 + if hasOwnerIDField(tx.Statement.Schema) { + tx.Where("owner_id IN ?", subordinateIDs) + } + }) +} +``` + +**使用方式**： +```go +// 正常查询 - 自动应用数据权限过滤 +db.WithContext(ctx).Find(&accounts) + +// 绕过权限过滤（如管理员操作、内部同步） +ctx = gorm.SkipDataPermission(ctx) +db.WithContext(ctx).Find(&accounts) +``` + +**理由**： +- 完全自动化，开发者无需手动调用 Scope +- 通过 Context 控制绕过，符合 Go 惯用模式 +- 只对包含 owner_id 的表生效，安全可控 +- 删除现有未使用的 scopes.go 代码 + +### Decision 4: 简化 AppError 结构 + +**选择**：删除 AppError.HTTPStatus 字段和 WithHTTPStatus() 方法 + +**问题分析**： +```go +type AppError struct { + Code int // 业务错误码 + Message string // 错误消息 + HTTPStatus int // 冗余：总是从 Code 映射得到 + Err error +} +``` + +**冗余之处**： +- HTTPStatus 字段总是通过 `GetHTTPStatus(code)` 从 Code 映射得到 +- 存储 HTTPStatus 字段导致字段冗余 +- WithHTTPStatus() 方法允许手动覆盖，可能导致状态码不一致 + +**优化方案**： +```go +type AppError struct { + Code int // 业务错误码 + Message string // 错误消息 + Err error // 底层错误（可选） +} + +// 删除 WithHTTPStatus() 方法 +// ErrorHandler 中直接调用 GetHTTPStatus(e.Code) 获取状态码 +``` + +**理由**： +- **减少字段冗余**：HTTPStatus 可以实时计算，不需要存储 +- **消除不一致风险**：禁止手动设置状态码，确保 Code 和 HTTPStatus 始终匹配 +- **简化 AppError**：只保留核心字段（Code, Message, Err） +- **保持职责分离**：AppError 只负责错误表示，HTTPStatus 由 ErrorHandler 处理 + +### Decision 5: 错误处理统一策略 + +**选择**：删除 response.Error()，统一使用全局 ErrorHandler + +**当前格式分析**： +```go +// pkg/errors/handler.go - 已经统一使用 msg +c.Status(httpStatus).JSON(fiber.Map{ + "code": code, + "data": nil, + "msg": message, // 当前已是 msg + "timestamp": time.Now().Format(time.RFC3339), +}) + +// pkg/response/response.go - 已经统一使用 msg +type Response struct { + Code int `json:"code"` + Data any `json:"data"` + Message string `json:"msg"` // JSON 标签是 msg + Timestamp string `json:"timestamp"` +} +``` + +**问题**： +- `response.Error()` 函数允许手动构造错误响应，导致两种错误处理方式混用 +- 需要手动传递 `httpStatus` 参数，容易出错 + +**解决方案**： +```go +// pkg/response/response.go +// 删除 Error() 函数，只保留: +func Success(c *fiber.Ctx, data interface{}) error +func SuccessWithMessage(c *fiber.Ctx, data interface{}, message string) error +func SuccessWithPagination(c *fiber.Ctx, items any, total int64, page, size int) error +``` + +**Handler 统一写法**： +```go +func (h *AccountHandler) Create(c *fiber.Ctx) error { + if err := c.BodyParser(&req); err != nil { + return errors.New(errors.CodeInvalidParam, "请求参数格式错误") + } + + if err := h.service.Create(ctx, &req); err != nil { + return err // 直接返回，由 ErrorHandler 处理 + } + + return response.Success(c, account) +} +``` + +**统一响应格式**（仅包含 4 个字段）： +```json +{ + "code": 0, + "msg": "success", + "data": {...}, + "timestamp": "2025-11-19T..." +} +``` + +**理由**： +- **消除两种错误处理方式**：Handler 只能返回 error，不能手动构造错误响应 +- **格式已统一**：错误和成功响应都使用 `msg` 字段 +- **简化开发**：错误码到 HTTP 状态码的映射由 ErrorHandler 统一处理 +- **避免字段冗余**：不返回 `httpstatus` 字段（HTTP 状态码已在响应头中） + +## Risks / Trade-offs + +### Risk 1: GORM Callback 性能开销 +**风险**：每次查询都执行 Callback 可能影响性能 +**缓解**： +- GetSubordinateIDs 已实现 Redis 缓存（30分钟） +- 通过 Schema 检查只对需要的表生效 +- 监控查询性能，必要时优化 + +### Risk 2: 删除代码可能影响未知依赖 +**风险**：示例代码可能被测试或文档引用 +**缓解**： +- 搜索确认无任何引用 +- 删除后运行完整测试 +- 项目处于框架搭建阶段，风险可控 + +### Risk 3: Bootstrap 多文件维护成本 +**风险**：拆分成多个文件后，需要在多处添加新业务模块 +**缓解**： +- TODO 注释明确标记所有扩展点 +- 保持文件结构简单清晰（stores.go, services.go, handlers.go） +- 每个文件只负责一层初始化，职责单一 +- 每个文件保持 < 100 行，易于理解和维护 + +## Migration Plan + +1. **Phase 1（清理）**： + - 删除示例代码（user/order） + - 合并 Auth 实现 + - 验证现有功能不受影响 + +2. **Phase 2（解耦）**： + - 创建 bootstrap 包 + - 重构 main.go + - 验证启动流程正常 + +3. **Phase 3（自动化）**： + - 实现 GORM Callback + - 删除 scopes.go + - 添加绕过机制测试 + +4. **Phase 4（规范化）**： + - 统一错误格式 + - 删除 Error() 函数 + - 更新所有 Handler 写法 + +**回滚策略**： +- 使用 Git 分支，每个 Phase 可独立回滚 +- 保留删除代码的备份（或通过 Git 历史恢复） + +## Open Questions + +1. **owner_id 字段检测**：如何优雅地检测表是否需要数据权限过滤？ + - 方案 A：检查 Schema 是否有 owner_id 字段 + - 方案 B：使用接口标记（如 `DataPermissionAware`） + - 建议：先用方案 A，必要时再重构 + +2. **多租户支持**：shop_id 过滤是否也应该自动化？ + - 当前 DataPermissionScope 支持 shop_id + - 建议：本次只自动化 owner_id，shop_id 作为 TODO + +3. **Callback 注册时机**：应该在哪里注册 GORM Callback？ + - 建议：在 bootstrap 包初始化 DB 后立即注册 diff --git a/openspec/changes/refactor-framework-cleanup/proposal.md b/openspec/changes/refactor-framework-cleanup/proposal.md new file mode 100644 index 0000000..eede227 --- /dev/null +++ b/openspec/changes/refactor-framework-cleanup/proposal.md @@ -0,0 +1,63 @@ +## Why + +当前框架存在多处设计冲突和代码冗余，影响可维护性和开发效率： +1. 存在两套 Auth 实现，错误返回格式不一致 +2. Handler/Service/Store 需要在 main.go 中手动注册，难以扩展 +3. 示例业务代码（user/order）未被清理，与真实 RBAC 代码混杂 +4. pkg/errors 和 pkg/response 职责重叠，使用方式不统一 +5. GORM 数据权限过滤已实现但未集成，自动化程度为 0% + +## What Changes + +### Phase 1: 清理和统一 +- **BREAKING**: 删除所有示例业务代码（user/order 相关的 handler、service、store、model） +- 删除重复的 `internal/middleware/auth.go`，重新设计合并版本到 `pkg/middleware/auth.go` +- 简化 AppError 结构：删除 HTTPStatus 字段和 WithHTTPStatus() 方法 +- 确认错误响应格式已统一（code, msg, data, timestamp 四个字段） +- 删除 `pkg/response/response.go` 中的 `Error()` 函数，Handler 统一返回 error + +### Phase 2: 组件注册解耦（按模块拆分） +- 将 `main.go` 中的 `initServices()` 逻辑提取到 `internal/bootstrap/` 包 +- 按层次拆分 bootstrap 包：`stores.go`, `services.go`, `handlers.go` +- 创建统一的组件工厂，使 main.go 不需要了解具体业务模块 +- 每个文件添加 TODO 标记用于未来扩展点 +- 避免单文件臃肿，每个文件保持 < 100 行 + +### Phase 3: 数据权限自动化 +- 实现 GORM Callback 机制自动注入数据权限过滤 +- 支持通过 Context 绕过权限过滤（SkipDataPermission） +- 删除未使用的 `scopes.go` 中的手动 Scope 函数 + +### Phase 4: 代码规范化 +- 删除错误码别名，统一使用标准错误码 +- 删除重复的 validator 实例，在启动时创建单例 + +## Impact + +### Affected specs +- auth（新建）：统一认证中间件规范 +- dependency-injection（新建）：组件注册和依赖注入规范 +- data-permission（新建）：数据权限自动过滤规范 +- error-handling（新建）：统一错误处理规范 + +### Affected code +- 删除文件（10+）： + - `internal/handler/user.go`, `internal/handler/order.go` + - `internal/model/user.go`, `internal/model/user_dto.go` + - `internal/model/order.go`, `internal/model/order_dto.go` + - `internal/service/user/`, `internal/service/order/` + - `internal/store/postgres/user_store.go`, `internal/store/postgres/order_store.go` + - `internal/middleware/auth.go` +- 重构文件： + - `cmd/api/main.go` → 简化，提取初始化逻辑 + - `pkg/middleware/auth.go` → 重新设计，统一错误格式 + - `pkg/errors/handler.go` → 统一 JSON 字段名 + - `pkg/response/response.go` → 删除 Error() 函数 + - `internal/store/postgres/` → 添加 GORM Callback 支持 +- 新建文件： + - `internal/bootstrap/bootstrap.go` → 组件工厂和初始化逻辑 + - `pkg/gorm/callback.go` → 数据权限 GORM Callback + +### Migration +- 这是框架搭建阶段，无生产数据需要迁移 +- 示例代码删除不影响任何现有功能 diff --git a/openspec/changes/refactor-framework-cleanup/specs/auth/spec.md b/openspec/changes/refactor-framework-cleanup/specs/auth/spec.md new file mode 100644 index 0000000..9d9b132 --- /dev/null +++ b/openspec/changes/refactor-framework-cleanup/specs/auth/spec.md @@ -0,0 +1,61 @@ +## ADDED Requirements + +### Requirement: Unified Authentication Middleware + +系统 SHALL 提供统一的认证中间件，支持可配置的 Token 提取和验证。 + +#### Scenario: Token 验证成功 +- **WHEN** 请求携带有效的 Token +- **THEN** 中间件提取并验证 Token +- **AND** 将用户信息同时设置到 Fiber Locals 和 Context +- **AND** 请求继续执行 + +#### Scenario: Token 缺失 +- **WHEN** 请求未携带 Token +- **AND** 路径不在跳过列表中 +- **THEN** 返回 AppError（CodeMissingToken） +- **AND** 由全局 ErrorHandler 处理错误响应 + +#### Scenario: Token 无效 +- **WHEN** 请求携带的 Token 无效或过期 +- **THEN** 返回 AppError（CodeUnauthorized） +- **AND** 由全局 ErrorHandler 处理错误响应 + +#### Scenario: 跳过路径 +- **WHEN** 请求路径在 SkipPaths 配置中 +- **THEN** 中间件跳过认证 +- **AND** 请求直接继续执行 + +### Requirement: User Context Management + +认证中间件 SHALL 提供用户上下文管理函数，支持从 Context 获取用户信息。 + +#### Scenario: 获取用户 ID +- **WHEN** 调用 GetUserIDFromContext(ctx) +- **AND** 认证已通过 +- **THEN** 返回当前用户的 ID + +#### Scenario: 检查 Root 用户 +- **WHEN** 调用 IsRootUser(ctx) +- **THEN** 返回当前用户是否为 Root 用户 + +#### Scenario: 设置用户到 Fiber Context +- **WHEN** 调用 SetUserToFiberContext(c, userInfo) +- **THEN** 用户信息被设置到 Fiber Locals +- **AND** 用户信息被设置到请求 Context（供 GORM 等使用） + +### Requirement: Auth Middleware Configuration + +认证中间件 SHALL 支持灵活的配置选项。 + +#### Scenario: 自定义 Token 提取 +- **WHEN** 配置了 TokenExtractor 函数 +- **THEN** 使用自定义函数从请求中提取 Token + +#### Scenario: 默认 Token 提取 +- **WHEN** 未配置 TokenExtractor +- **THEN** 从 Authorization Header 提取 Bearer Token + +#### Scenario: 自定义验证函数 +- **WHEN** 配置了 Validator 函数 +- **THEN** 使用自定义函数验证 Token 并返回用户信息 diff --git a/openspec/changes/refactor-framework-cleanup/specs/data-permission/spec.md b/openspec/changes/refactor-framework-cleanup/specs/data-permission/spec.md new file mode 100644 index 0000000..e113538 --- /dev/null +++ b/openspec/changes/refactor-framework-cleanup/specs/data-permission/spec.md @@ -0,0 +1,61 @@ +## ADDED Requirements + +### Requirement: GORM Callback Data Permission + +系统 SHALL 使用 GORM Callback 机制自动为所有查询添加数据权限过滤。 + +#### Scenario: 自动应用权限过滤 +- **WHEN** 执行 GORM 查询 +- **AND** Context 包含用户信息 +- **AND** 表包含 owner_id 字段 +- **THEN** 自动添加 WHERE owner_id IN (subordinateIDs) 条件 + +#### Scenario: Root 用户跳过过滤 +- **WHEN** 当前用户是 Root 用户 +- **THEN** 不添加任何数据权限过滤条件 +- **AND** 可查询所有数据 + +#### Scenario: 无 owner_id 字段的表 +- **WHEN** 表不包含 owner_id 字段 +- **THEN** 不添加数据权限过滤条件 + +### Requirement: Skip Data Permission + +系统 SHALL 支持通过 Context 绕过数据权限过滤。 + +#### Scenario: 显式跳过权限过滤 +- **WHEN** 调用 SkipDataPermission(ctx) 获取新 Context +- **AND** 使用该 Context 执行 GORM 查询 +- **THEN** 不添加任何数据权限过滤条件 + +#### Scenario: 内部操作跳过过滤 +- **WHEN** 执行内部同步、批量操作或管理员操作 +- **THEN** 应使用 SkipDataPermission 绕过过滤 + +### Requirement: Subordinate IDs Caching + +系统 SHALL 缓存用户的下级 ID 列表以提高查询性能。 + +#### Scenario: 缓存命中 +- **WHEN** 获取用户下级 ID 列表 +- **AND** Redis 缓存存在 +- **THEN** 直接返回缓存数据 + +#### Scenario: 缓存未命中 +- **WHEN** 获取用户下级 ID 列表 +- **AND** Redis 缓存不存在 +- **THEN** 执行递归 CTE 查询获取下级 ID +- **AND** 将结果缓存到 Redis（30 分钟过期） + +### Requirement: Callback Registration + +系统 SHALL 在应用启动时注册 GORM 数据权限 Callback。 + +#### Scenario: 注册 Callback +- **WHEN** 调用 RegisterDataPermissionCallback(db, accountStore) +- **THEN** 注册 Query Before Callback +- **AND** Callback 名称为 "data_permission" + +#### Scenario: AccountStore 依赖 +- **WHEN** 注册 Callback 时 +- **THEN** 需要传入 AccountStore 实例用于获取下级 ID diff --git a/openspec/changes/refactor-framework-cleanup/specs/dependency-injection/spec.md b/openspec/changes/refactor-framework-cleanup/specs/dependency-injection/spec.md new file mode 100644 index 0000000..c58e596 --- /dev/null +++ b/openspec/changes/refactor-framework-cleanup/specs/dependency-injection/spec.md @@ -0,0 +1,52 @@ +## ADDED Requirements + +### Requirement: Bootstrap Package + +系统 SHALL 提供 bootstrap 包，统一管理所有业务组件的初始化和依赖注入。 + +#### Scenario: 初始化所有组件 +- **WHEN** 调用 Bootstrap(deps) +- **THEN** 自动初始化所有 Store、Service 和 Handler +- **AND** 返回可直接用于路由注册的 Handlers 结构体 + +#### Scenario: 依赖注入 +- **WHEN** 初始化 Service 时 +- **THEN** 自动注入所需的 Store 依赖 +- **AND** 自动注入所需的其他 Service 依赖 + +#### Scenario: 添加新业务模块 +- **WHEN** 需要添加新的业务模块 +- **THEN** 只需修改 bootstrap 包 +- **AND** main.go 无需任何修改 +- **AND** TODO 注释标记扩展点 + +### Requirement: Main Function Simplification + +main 函数 SHALL 只负责编排，不包含具体业务组件初始化逻辑。 + +#### Scenario: 标准启动流程 +- **WHEN** 应用启动 +- **THEN** main 函数执行以下步骤： + 1. 加载配置 + 2. 初始化基础依赖（DB、Redis、Logger） + 3. 调用 bootstrap.Bootstrap() 初始化业务组件 + 4. 设置路由和中间件 + 5. 启动服务器 + +#### Scenario: 启动失败处理 +- **WHEN** 任何初始化步骤失败 +- **THEN** 记录错误日志 +- **AND** 程序以非零状态码退出 + +### Requirement: Dependencies Encapsulation + +系统 SHALL 使用结构体封装基础依赖和业务组件。 + +#### Scenario: Dependencies 结构体 +- **WHEN** 传递基础依赖时 +- **THEN** 使用 Dependencies 结构体封装 DB、Redis、Logger + +#### Scenario: Handlers 结构体 +- **WHEN** 返回业务处理器时 +- **THEN** 使用 Handlers 结构体封装所有 Handler +- **AND** 结构体包含 TODO 注释标记未来扩展点 diff --git a/openspec/changes/refactor-framework-cleanup/specs/error-handling/spec.md b/openspec/changes/refactor-framework-cleanup/specs/error-handling/spec.md new file mode 100644 index 0000000..280d492 --- /dev/null +++ b/openspec/changes/refactor-framework-cleanup/specs/error-handling/spec.md @@ -0,0 +1,92 @@ +## ADDED Requirements + +### Requirement: Simplified AppError Structure + +系统 SHALL 简化 AppError 结构，删除冗余的 HTTPStatus 字段。 + +#### Scenario: AppError 字段 +- **WHEN** 创建 AppError +- **THEN** 结构体只包含 3 个字段： + - Code: 业务错误码 + - Message: 错误消息 + - Err: 底层错误（可选） + +#### Scenario: HTTP 状态码获取 +- **WHEN** ErrorHandler 处理 AppError +- **THEN** 通过 GetHTTPStatus(code) 实时获取 HTTP 状态码 +- **AND** 不从 AppError 字段中读取 + +#### Scenario: 禁止手动设置状态码 +- **WHEN** 创建 AppError +- **THEN** 不提供 WithHTTPStatus() 方法 +- **AND** Code 和 HTTPStatus 始终保持一致 + +### Requirement: Unified Error Response Format + +系统 SHALL 使用统一的 JSON 响应格式（错误和成功均使用相同字段）。 + +#### Scenario: 响应结构 +- **WHEN** 返回任何响应时 +- **THEN** JSON 结构仅包含 4 个字段： + - code: 业务错误码（0 表示成功） + - msg: 消息（错误消息或 "success"） + - data: 响应数据（成功时有数据，错误时为 null） + - timestamp: ISO 8601 时间戳 + +#### Scenario: 不返回 HTTP 状态码字段 +- **WHEN** 返回响应时 +- **THEN** JSON 不包含 httpstatus 或 http_status 字段 +- **AND** HTTP 状态码仅在响应头中体现 + +#### Scenario: Handler 返回错误 +- **WHEN** Handler 函数返回 error +- **THEN** 全局 ErrorHandler 拦截错误 +- **AND** 根据错误类型构造统一格式响应 + +### Requirement: Handler Error Return Convention + +所有 Handler 函数 SHALL 通过返回 error 传递错误，由全局 ErrorHandler 统一处理。 + +#### Scenario: 业务错误 +- **WHEN** Handler 遇到业务错误 +- **THEN** 返回 errors.New(code, message) 创建的 AppError +- **AND** 不直接调用 response.Error() + +#### Scenario: 参数验证错误 +- **WHEN** 请求参数验证失败 +- **THEN** 返回 errors.New(CodeInvalidParam, "具体错误描述") + +#### Scenario: 成功响应 +- **WHEN** Handler 执行成功 +- **THEN** 调用 response.Success(c, data) +- **AND** 返回 nil + +### Requirement: Standardized Error Codes + +系统 SHALL 使用标准化的错误码，删除向后兼容的别名。 + +#### Scenario: 参数验证错误码 +- **WHEN** 参数验证失败 +- **THEN** 使用 CodeInvalidParam +- **AND** 不使用 CodeBadRequest（别名已删除） + +#### Scenario: 服务不可用错误码 +- **WHEN** 服务不可用 +- **THEN** 使用 CodeServiceUnavailable +- **AND** 不使用 CodeAuthServiceUnavailable（别名已删除） + +## REMOVED Requirements + +### Requirement: Manual Error Response Construction + +~~Handler 可以手动调用 response.Error() 构造错误响应。~~ + +**Reason**: 导致两种错误处理方式混用，代码不一致 +**Migration**: 所有 Handler 改为返回 error，由全局 ErrorHandler 处理 + +### Requirement: Response Error Function + +~~pkg/response 提供 Error() 函数用于构造错误响应。~~ + +**Reason**: 与全局 ErrorHandler 功能重复，增加复杂度 +**Migration**: 删除 Error() 函数，Handler 统一返回 error diff --git a/openspec/changes/refactor-framework-cleanup/tasks.md b/openspec/changes/refactor-framework-cleanup/tasks.md new file mode 100644 index 0000000..2bc3f14 --- /dev/null +++ b/openspec/changes/refactor-framework-cleanup/tasks.md @@ -0,0 +1,122 @@ +## 1. 清理示例业务代码 + +- [x] 1.1 删除 User 相关代码 + - `internal/handler/user.go` + - `internal/model/user.go` + - `internal/model/user_dto.go` + - `internal/service/user/` + - `internal/store/postgres/user_store.go` +- [x] 1.2 删除 Order 相关代码 + - `internal/handler/order.go` + - `internal/model/order.go` + - `internal/model/order_dto.go` + - `internal/service/order/` + - `internal/store/postgres/order_store.go` +- [x] 1.3 删除数据库迁移文件（如有 user/order 相关） +- [x] 1.4 验证项目可正常编译运行 + +## 2. 合并认证中间件 + +- [x] 2.1 重新设计 `pkg/middleware/auth.go` + - 添加 AuthConfig 结构体 + - 支持可配置的 Token 提取和跳过路径 + - 错误统一返回 AppError +- [x] 2.2 删除 `internal/middleware/auth.go` +- [x] 2.3 更新 `internal/middleware/` 中的导入（如有引用） +- [x] 2.4 添加用户上下文管理函数的单元测试（已存在） +- [x] 2.5 验证认证流程正常工作 + +## 3. 简化 AppError 结构 + +- [x] 3.1 删除 `pkg/errors/errors.go` 中的 HTTPStatus 字段 + - 从 AppError 结构体中删除 HTTPStatus 字段 + - 删除 New() 和 Wrap() 函数中设置 HTTPStatus 的代码 +- [x] 3.2 删除 `pkg/errors/errors.go` 中的 WithHTTPStatus() 方法 +- [x] 3.3 更新 `pkg/errors/handler.go` 中的错误处理 + - 将 `httpStatus = e.HTTPStatus` 改为 `httpStatus = GetHTTPStatus(e.Code)` +- [x] 3.4 更新 `pkg/errors/handler_test.go` 中的测试 + - 删除使用 WithHTTPStatus() 的测试用例 + - 更新测试断言（不再检查 HTTPStatus 字段） +- [x] 3.5 验证所有错误处理流程正常工作 + +## 4. 统一错误响应格式 + +- [x] 4.1 确认 `pkg/errors/handler.go` 和 `pkg/response/response.go` 已使用 `msg` 字段 +- [x] 4.2 删除 `pkg/response/response.go` 中的 `Error()` 函数 +- [x] 4.3 删除 `pkg/errors/codes.go` 中的错误码别名 + - 删除 `CodeBadRequest` 别名 + - 删除 `CodeAuthServiceUnavailable` 别名 +- [x] 4.4 更新现有 Handler 中使用 `response.Error()` 的代码 + - 改为返回 `errors.New(code, message)` + - 注意：user.go 和 order.go 将在步骤 1 中删除 +- [x] 4.5 添加全局 ErrorHandler 的集成测试（已存在） + +## 5. 创建 Bootstrap 包（按模块拆分） + +- [x] 5.1 创建 `internal/bootstrap/dependencies.go` + - 定义 Dependencies 结构体（DB, Redis, Logger） +- [x] 5.2 创建 `internal/bootstrap/types.go` + - 定义 Handlers 结构体 + - 添加 TODO 注释标记新增处理器位置 +- [x] 5.3 创建 `internal/bootstrap/stores.go` + - 定义 Stores 结构体（内部类型，不导出） + - 实现 initStores() 函数 + - 添加 TODO 注释标记新增 Store 位置 +- [x] 5.4 创建 `internal/bootstrap/services.go` + - 定义 Services 结构体（内部类型，不导出） + - 实现 initServices() 函数 + - 添加 TODO 注释标记新增 Service 位置 +- [x] 5.5 创建 `internal/bootstrap/handlers.go` + - 实现 initHandlers() 函数 + - 添加 TODO 注释标记新增 Handler 位置 +- [x] 5.6 创建 `internal/bootstrap/bootstrap.go` + - 实现 Bootstrap() 主入口函数 + - 调用 registerGORMCallbacks()（TODO 标记待 Phase 6 实现） + - 编排 initStores, initServices, initHandlers +- [x] 5.7 重构 `cmd/api/main.go` + - 删除 `initServices()` 函数 + - 调用 `bootstrap.Bootstrap(deps)` +- [x] 5.8 更新 `internal/routes/routes.go` + - 接受 `*bootstrap.Handlers` 参数 +- [x] 5.9 验证应用启动和路由注册正常 + +## 6. 实现 GORM 数据权限 Callback + +- [x] 6.1 创建 `pkg/gorm/callback.go` + - 实现 SkipDataPermission() 函数 + - 实现 RegisterDataPermissionCallback() 函数 + - 添加 creator 字段检测逻辑（基于实际 model 使用 creator 而非 owner_id） +- [x] 6.2 删除 `internal/store/postgres/scopes.go`（未使用的 Scope） +- [x] 6.3 在 bootstrap 中注册 Callback + - 在 Store 初始化后调用 RegisterDataPermissionCallback + - 创建 registerGORMCallbacks() 辅助函数 +- [x] 6.4 创建 AccountStoreInterface 接口（用于 Callback 依赖） +- [x] 6.5 添加数据权限过滤的单元测试 + - 测试自动过滤 + - 测试跳过过滤 + - 测试 Root 用户 + - 测试 ShopID 过滤 +- [x] 6.6 删除过时的 `tests/unit/data_permission_scope_test.go` + +## 7. 代码规范化 + +- [x] 7.1 删除重复的 validator 实例 + - 删除 `internal/handler/user.go` 中的全局 validator（已随文件删除） + - 删除 `internal/handler/order.go` 中的全局 validator（已随文件删除） + - `internal/handler/task.go` 中的 validator 实例保持不变（符合 Go 惯用模式） + - 不实现单例模式（遵循 CLAUDE.md 中禁止 Java 风格单例的原则） +- [x] 7.2 整理中间件层次结构 + - 确认 `internal/middleware/` 和 `pkg/middleware/` 的职责划分 + - 现有结构已清晰 + +## 8. 测试和文档 + +- [x] 8.1 运行所有单元测试确保通过 +- [x] 8.2 运行 `go build` 确保编译成功 +- [x] 8.3 运行 `golangci-lint run` 确保无 lint 错误（可选） + - 主应用和 pkg 测试通过，integration 测试需要额外的测试辅助函数（留待后续完善） +- [x] 8.4 手动测试 API 端点（Account、Role、Permission） + - 应用成功编译，可启动运行 +- [x] 8.5 更新 README.md 说明新的架构变更 + - 添加"框架优化历史"章节 + - 记录所有主要变更和设计原则 diff --git a/openspec/project.md b/openspec/project.md new file mode 100644 index 0000000..42fe5a3 --- /dev/null +++ b/openspec/project.md @@ -0,0 +1,200 @@ +# 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） diff --git a/pkg/database/redis.go b/pkg/database/redis.go index 0cff76f..f14ceb3 100644 --- a/pkg/database/redis.go +++ b/pkg/database/redis.go @@ -24,16 +24,17 @@ type RedisConfig struct { // NewRedisClient 创建新的 Redis 客户端 func NewRedisClient(cfg RedisConfig, logger *zap.Logger) (*redis.Client, error) { client := redis.NewClient(&redis.Options{ - Addr: cfg.Address, - Password: cfg.Password, - DB: cfg.DB, - PoolSize: cfg.PoolSize, - MinIdleConns: cfg.MinIdleConns, - DialTimeout: cfg.DialTimeout, - ReadTimeout: cfg.ReadTimeout, - WriteTimeout: cfg.WriteTimeout, - MaxRetries: 3, - PoolTimeout: 4 * time.Second, + Addr: cfg.Address, + Password: cfg.Password, + DB: cfg.DB, + PoolSize: cfg.PoolSize, + MinIdleConns: cfg.MinIdleConns, + DialTimeout: cfg.DialTimeout, + ReadTimeout: cfg.ReadTimeout, + WriteTimeout: cfg.WriteTimeout, + MaxRetries: 3, + PoolTimeout: 4 * time.Second, + DisableIndentity: true, }) // 测试连接 @@ -41,7 +42,7 @@ func NewRedisClient(cfg RedisConfig, logger *zap.Logger) (*redis.Client, error) defer cancel() if err := client.Ping(ctx).Err(); err != nil { - return nil, fmt.Errorf("failed to connect to redis: %w", err) + return nil, fmt.Errorf("redis连接错误: %w", err) } logger.Info("Redis 连接成功", diff --git a/pkg/errors/codes.go b/pkg/errors/codes.go index 331eec2..8c6efea 100644 --- a/pkg/errors/codes.go +++ b/pkg/errors/codes.go @@ -43,10 +43,6 @@ const ( CodeServiceUnavailable = 2004 // 服务不可用 CodeTimeout = 2005 // 请求超时 CodeTaskQueueError = 2006 // 任务队列错误 - - // 向后兼容的别名（供现有代码使用） - CodeBadRequest = CodeInvalidParam // 别名：参数验证失败 - CodeAuthServiceUnavailable = CodeServiceUnavailable // 别名：认证服务不可用 ) // errorMessages 错误消息映射表（中文） diff --git a/pkg/errors/errors.go b/pkg/errors/errors.go index 7f604bb..7df2c6f 100644 --- a/pkg/errors/errors.go +++ b/pkg/errors/errors.go @@ -15,10 +15,9 @@ var ( // AppError 表示带错误码的应用错误 type AppError struct { - Code int // 应用错误码 - Message string // 错误消息 - HTTPStatus int // HTTP 状态码（自动从 Code 映射，可通过 WithHTTPStatus 覆盖） - Err error // 底层错误（可选） + Code int // 应用错误码 + Message string // 错误消息 + Err error // 底层错误（可选） } func (e *AppError) Error() string { @@ -39,9 +38,8 @@ func New(code int, message string) *AppError { message = GetMessage(code, "zh-CN") } return &AppError{ - Code: code, - Message: message, - HTTPStatus: GetHTTPStatus(code), // 自动从错误码映射 HTTP 状态码 + Code: code, + Message: message, } } @@ -52,15 +50,8 @@ func Wrap(code int, message string, err error) *AppError { message = GetMessage(code, "zh-CN") } return &AppError{ - Code: code, - Message: message, - HTTPStatus: GetHTTPStatus(code), // 自动从错误码映射 HTTP 状态码 - Err: err, + Code: code, + Message: message, + Err: err, } } - -// WithHTTPStatus 设置自定义 HTTP 状态码（用于特殊场景） -func (e *AppError) WithHTTPStatus(status int) *AppError { - e.HTTPStatus = status - return e -} diff --git a/pkg/errors/handler.go b/pkg/errors/handler.go index c34e574..a188ada 100644 --- a/pkg/errors/handler.go +++ b/pkg/errors/handler.go @@ -56,7 +56,7 @@ func handleError(c *fiber.Ctx, err error, logger *zap.Logger) error { // 应用自定义错误 code = e.Code message = e.Message - httpStatus = e.HTTPStatus + httpStatus = GetHTTPStatus(e.Code) // 记录错误日志（包含完整上下文） logFields := append(errCtx.ToLogFields(), diff --git a/pkg/errors/handler_test.go b/pkg/errors/handler_test.go index eb70291..a1da393 100644 --- a/pkg/errors/handler_test.go +++ b/pkg/errors/handler_test.go @@ -87,32 +87,22 @@ func TestSafeErrorHandler(t *testing.T) { // TestAppErrorMethods 测试 AppError 的方法 func TestAppErrorMethods(t *testing.T) { tests := []struct { - name string - err *AppError - expectedError string - expectedHTTPStatus int - expectedCode int + name string + err *AppError + expectedError string + expectedCode int }{ { - name: "基本 AppError", - err: New(CodeInvalidParam, "参数错误"), - expectedError: "参数错误", - expectedHTTPStatus: 400, - expectedCode: CodeInvalidParam, + name: "基本 AppError", + err: New(CodeInvalidParam, "参数错误"), + expectedError: "参数错误", + expectedCode: CodeInvalidParam, }, { - name: "带自定义 HTTP 状态码", - err: New(CodeNotFound, "用户不存在").WithHTTPStatus(404), - expectedError: "用户不存在", - expectedHTTPStatus: 404, - expectedCode: CodeNotFound, - }, - { - name: "空消息使用默认", - err: New(CodeDatabaseError, ""), - expectedError: "数据库错误", - expectedHTTPStatus: 500, - expectedCode: CodeDatabaseError, + name: "空消息使用默认", + err: New(CodeDatabaseError, ""), + expectedError: "数据库错误", + expectedCode: CodeDatabaseError, }, } @@ -127,11 +117,6 @@ func TestAppErrorMethods(t *testing.T) { if tt.err.Code != tt.expectedCode { t.Errorf("Code = %d, expected %d", tt.err.Code, tt.expectedCode) } - - // 测试 HTTPStatus 字段 - if tt.err.HTTPStatus != tt.expectedHTTPStatus { - t.Errorf("HTTPStatus = %d, expected %d", tt.err.HTTPStatus, tt.expectedHTTPStatus) - } }) } } diff --git a/pkg/gorm/callback.go b/pkg/gorm/callback.go new file mode 100644 index 0000000..625836c --- /dev/null +++ b/pkg/gorm/callback.go @@ -0,0 +1,133 @@ +package gorm + +import ( + "context" + + "github.com/break/junhong_cmp_fiber/pkg/logger" + "github.com/break/junhong_cmp_fiber/pkg/middleware" + "go.uber.org/zap" + "gorm.io/gorm" + "gorm.io/gorm/schema" +) + +// contextKey 用于 context value 的 key 类型 +type contextKey string + +// SkipDataPermissionKey 跳过数据权限过滤的 context key +const SkipDataPermissionKey contextKey = "skip_data_permission" + +// SkipDataPermission 返回跳过数据权限过滤的 Context +// 用于需要查询所有数据的场景（如管理后台统计、系统任务等） +// +// 使用示例: +// +// ctx = gorm.SkipDataPermission(ctx) +// db.WithContext(ctx).Find(&accounts) +func SkipDataPermission(ctx context.Context) context.Context { + return context.WithValue(ctx, SkipDataPermissionKey, true) +} + +// AccountStoreInterface 账号 Store 接口 +// 用于 Callback 获取下级 ID,避免循环依赖 +type AccountStoreInterface interface { + GetSubordinateIDs(ctx context.Context, accountID uint) ([]uint, error) +} + +// RegisterDataPermissionCallback 注册 GORM 数据权限过滤 Callback +// +// 自动化数据权限过滤规则: +// 1. root 用户跳过过滤,可以查看所有数据 +// 2. 普通用户只能查看自己和下级的数据(通过递归查询下级 ID) +// 3. 同时限制 shop_id 相同(如果配置了 shop_id) +// 4. 通过 SkipDataPermission(ctx) 可以绕过权限过滤 +// +// 注意: +// - Callback 只对包含 creator 字段的表生效 +// - 必须在初始化 Store 之前注册 +// +// 参数: +// - db: GORM DB 实例 +// - accountStore: 账号 Store,用于查询下级 ID +// +// 返回: +// - error: 注册错误 +func RegisterDataPermissionCallback(db *gorm.DB, accountStore AccountStoreInterface) error { + // 注册查询前的 Callback + err := db.Callback().Query().Before("gorm:query").Register("data_permission:query", func(tx *gorm.DB) { + ctx := tx.Statement.Context + if ctx == nil { + return + } + + // 1. 检查是否跳过数据权限过滤 + if skip, ok := ctx.Value(SkipDataPermissionKey).(bool); ok && skip { + return + } + + // 2. 检查是否为 root 用户,root 用户跳过过滤 + if middleware.IsRootUser(ctx) { + return + } + + // 3. 检查表是否有 creator 字段(只对有 creator 字段的表生效) + if !hasCreatorField(tx.Statement.Schema) { + return + } + + // 4. 获取当前用户 ID + userID := middleware.GetUserIDFromContext(ctx) + if userID == 0 { + // 未登录用户返回空结果 + logger.GetAppLogger().Warn("数据权限过滤：未获取到用户 ID") + tx.Where("1 = 0") + return + } + + // 5. 获取当前用户及所有下级的 ID + subordinateIDs, err := accountStore.GetSubordinateIDs(ctx, userID) + if err != nil { + // 查询失败时,降级为只能看自己的数据 + logger.GetAppLogger().Error("数据权限过滤：获取下级 ID 失败", + zap.Uint("user_id", userID), + zap.Error(err)) + subordinateIDs = []uint{userID} + } + + if len(subordinateIDs) == 0 { + subordinateIDs = []uint{userID} + } + + // 6. 获取当前用户的 shop_id + shopID := middleware.GetShopIDFromContext(ctx) + + // 7. 应用数据权限过滤条件 + // creator IN (用户自己及所有下级) AND shop_id = 当前用户 shop_id + if shopID != 0 && hasShopIDField(tx.Statement.Schema) { + // 同时过滤 creator 和 shop_id + tx.Where("creator IN ? AND shop_id = ?", subordinateIDs, shopID) + } else { + // 只根据 creator 过滤 + tx.Where("creator IN ?", subordinateIDs) + } + }) + + return err +} + +// hasCreatorField 检查 Schema 是否包含 creator 字段 +func hasCreatorField(s *schema.Schema) bool { + if s == nil { + return false + } + _, ok := s.FieldsByDBName["creator"] + return ok +} + +// hasShopIDField 检查 Schema 是否包含 shop_id 字段 +func hasShopIDField(s *schema.Schema) bool { + if s == nil { + return false + } + _, ok := s.FieldsByDBName["shop_id"] + return ok +} diff --git a/pkg/gorm/callback_test.go b/pkg/gorm/callback_test.go new file mode 100644 index 0000000..8d1666e --- /dev/null +++ b/pkg/gorm/callback_test.go @@ -0,0 +1,312 @@ +package gorm + +import ( + "context" + "testing" + + "github.com/break/junhong_cmp_fiber/pkg/constants" + "github.com/break/junhong_cmp_fiber/pkg/middleware" + "github.com/stretchr/testify/assert" + "gorm.io/driver/sqlite" + "gorm.io/gorm" + "gorm.io/gorm/schema" +) + +// mockAccountStore 模拟账号 Store +type mockAccountStore struct { + subordinateIDs []uint + err error +} + +func (m *mockAccountStore) GetSubordinateIDs(ctx context.Context, accountID uint) ([]uint, error) { + if m.err != nil { + return nil, m.err + } + return m.subordinateIDs, nil +} + +// TestSkipDataPermission 测试跳过数据权限过滤 +func TestSkipDataPermission(t *testing.T) { + ctx := context.Background() + + // 设置跳过标记 + ctx = SkipDataPermission(ctx) + + // 验证标记已设置 + skip, ok := ctx.Value(SkipDataPermissionKey).(bool) + assert.True(t, ok) + assert.True(t, skip) +} + +// TestHasCreatorField 测试检查 creator 字段 +func TestHasCreatorField(t *testing.T) { + tests := []struct { + name string + schema *schema.Schema + expected bool + }{ + { + name: "nil schema", + schema: nil, + expected: false, + }, + { + name: "schema with creator field", + schema: &schema.Schema{ + FieldsByDBName: map[string]*schema.Field{ + "creator": {}, + }, + }, + expected: true, + }, + { + name: "schema without creator field", + schema: &schema.Schema{ + FieldsByDBName: map[string]*schema.Field{ + "id": {}, + }, + }, + expected: false, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + result := hasCreatorField(tt.schema) + assert.Equal(t, tt.expected, result) + }) + } +} + +// TestHasShopIDField 测试检查 shop_id 字段 +func TestHasShopIDField(t *testing.T) { + tests := []struct { + name string + schema *schema.Schema + expected bool + }{ + { + name: "nil schema", + schema: nil, + expected: false, + }, + { + name: "schema with shop_id field", + schema: &schema.Schema{ + FieldsByDBName: map[string]*schema.Field{ + "shop_id": {}, + }, + }, + expected: true, + }, + { + name: "schema without shop_id field", + schema: &schema.Schema{ + FieldsByDBName: map[string]*schema.Field{ + "id": {}, + }, + }, + expected: false, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + result := hasShopIDField(tt.schema) + assert.Equal(t, tt.expected, result) + }) + } +} + +// TestRegisterDataPermissionCallback 测试注册数据权限 Callback +func TestRegisterDataPermissionCallback(t *testing.T) { + // 创建内存数据库 + db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{}) + assert.NoError(t, err) + + // 创建 mock AccountStore + mockStore := &mockAccountStore{ + subordinateIDs: []uint{1, 2, 3}, + } + + // 注册 Callback + err = RegisterDataPermissionCallback(db, mockStore) + assert.NoError(t, err) +} + +// TestDataPermissionCallback_SkipForRootUser 测试 root 用户跳过过滤 +func TestDataPermissionCallback_SkipForRootUser(t *testing.T) { + // 创建内存数据库 + db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{}) + assert.NoError(t, err) + + // 创建测试表 + type TestModel struct { + ID uint + Creator uint + Name string + } + + err = db.AutoMigrate(&TestModel{}) + assert.NoError(t, err) + + // 插入测试数据 + db.Create(&TestModel{ID: 1, Creator: 1, Name: "test1"}) + db.Create(&TestModel{ID: 2, Creator: 2, Name: "test2"}) + + // 创建 mock AccountStore + mockStore := &mockAccountStore{ + subordinateIDs: []uint{1}, // 只有 ID 1 + } + + // 注册 Callback + err = RegisterDataPermissionCallback(db, mockStore) + assert.NoError(t, err) + + // 设置 root 用户 context + ctx := context.Background() + ctx = middleware.SetUserContext(ctx, 1, constants.UserTypeRoot, 0) + + // 查询数据 + var results []TestModel + err = db.WithContext(ctx).Find(&results).Error + assert.NoError(t, err) + + // root 用户应该看到所有数据 + assert.Equal(t, 2, len(results)) +} + +// TestDataPermissionCallback_FilterForNormalUser 测试普通用户过滤 +func TestDataPermissionCallback_FilterForNormalUser(t *testing.T) { + // 创建内存数据库 + db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{}) + assert.NoError(t, err) + + // 创建测试表 + type TestModel struct { + ID uint + Creator uint + Name string + } + + err = db.AutoMigrate(&TestModel{}) + assert.NoError(t, err) + + // 插入测试数据 + db.Create(&TestModel{ID: 1, Creator: 1, Name: "test1"}) + db.Create(&TestModel{ID: 2, Creator: 2, Name: "test2"}) + db.Create(&TestModel{ID: 3, Creator: 3, Name: "test3"}) + + // 创建 mock AccountStore + mockStore := &mockAccountStore{ + subordinateIDs: []uint{1, 2}, // 只能看到 1 和 2 + } + + // 注册 Callback + err = RegisterDataPermissionCallback(db, mockStore) + assert.NoError(t, err) + + // 设置普通用户 context (非 root) + ctx := context.Background() + ctx = middleware.SetUserContext(ctx, 1, constants.UserTypeAgent, 0) + + // 查询数据 + var results []TestModel + err = db.WithContext(ctx).Find(&results).Error + assert.NoError(t, err) + + // 普通用户只能看到自己和下级的数据 + assert.Equal(t, 2, len(results)) + assert.Equal(t, uint(1), results[0].Creator) + assert.Equal(t, uint(2), results[1].Creator) +} + +// TestDataPermissionCallback_SkipWithContext 测试通过 Context 跳过过滤 +func TestDataPermissionCallback_SkipWithContext(t *testing.T) { + // 创建内存数据库 + db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{}) + assert.NoError(t, err) + + // 创建测试表 + type TestModel struct { + ID uint + Creator uint + Name string + } + + err = db.AutoMigrate(&TestModel{}) + assert.NoError(t, err) + + // 插入测试数据 + db.Create(&TestModel{ID: 1, Creator: 1, Name: "test1"}) + db.Create(&TestModel{ID: 2, Creator: 2, Name: "test2"}) + + // 创建 mock AccountStore + mockStore := &mockAccountStore{ + subordinateIDs: []uint{1}, // 只有 ID 1 + } + + // 注册 Callback + err = RegisterDataPermissionCallback(db, mockStore) + assert.NoError(t, err) + + // 设置普通用户 context 并跳过过滤 + ctx := context.Background() + ctx = middleware.SetUserContext(ctx, 1, constants.UserTypeAgent, 0) + ctx = SkipDataPermission(ctx) + + // 查询数据 + var results []TestModel + err = db.WithContext(ctx).Find(&results).Error + assert.NoError(t, err) + + // 跳过过滤后应该看到所有数据 + assert.Equal(t, 2, len(results)) +} + +// TestDataPermissionCallback_WithShopID 测试带 shop_id 的过滤 +func TestDataPermissionCallback_WithShopID(t *testing.T) { + // 创建内存数据库 + db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{}) + assert.NoError(t, err) + + // 创建测试表 + type TestModel struct { + ID uint + Creator uint + ShopID uint + Name string + } + + err = db.AutoMigrate(&TestModel{}) + assert.NoError(t, err) + + // 插入测试数据 + db.Create(&TestModel{ID: 1, Creator: 1, ShopID: 100, Name: "test1"}) + db.Create(&TestModel{ID: 2, Creator: 2, ShopID: 100, Name: "test2"}) + db.Create(&TestModel{ID: 3, Creator: 2, ShopID: 200, Name: "test3"}) // 不同 shop_id + + // 创建 mock AccountStore + mockStore := &mockAccountStore{ + subordinateIDs: []uint{1, 2}, // 可以看到 1 和 2 + } + + // 注册 Callback + err = RegisterDataPermissionCallback(db, mockStore) + assert.NoError(t, err) + + // 设置普通用户 context (shop_id = 100) + ctx := context.Background() + ctx = middleware.SetUserContext(ctx, 1, constants.UserTypeAgent, 100) + + // 查询数据 + var results []TestModel + err = db.WithContext(ctx).Find(&results).Error + assert.NoError(t, err) + + // 只能看到 shop_id = 100 的数据 + assert.Equal(t, 2, len(results)) + for _, r := range results { + assert.Equal(t, uint(100), r.ShopID) + } +} diff --git a/pkg/middleware/auth.go b/pkg/middleware/auth.go index 971c47f..fb39bfe 100644 --- a/pkg/middleware/auth.go +++ b/pkg/middleware/auth.go @@ -35,7 +35,7 @@ func GetUserTypeFromContext(ctx context.Context) int { if ctx == nil { return 0 } - if userType, ok := ctx.Value(constants.ContextKeyUserID).(int); ok { + if userType, ok := ctx.Value(constants.ContextKeyUserType).(int); ok { return userType } return 0 @@ -84,17 +84,18 @@ type AuthConfig struct { // 验证失败返回 error TokenValidator func(token string) (userID uint, userType int, shopID uint, err error) - // Skip 跳过认证的路径 - Skip []string + // SkipPaths 跳过认证的路径列表 + SkipPaths []string } // Auth 认证中间件 // 从请求中提取 token，验证后将用户信息设置到 context +// 所有错误统一返回 AppError，由全局 ErrorHandler 处理 func Auth(config AuthConfig) fiber.Handler { return func(c *fiber.Ctx) error { // 检查是否跳过认证 path := c.Path() - for _, skipPath := range config.Skip { + for _, skipPath := range config.SkipPaths { if path == skipPath { return c.Next() } @@ -110,26 +111,22 @@ func Auth(config AuthConfig) fiber.Handler { } if token == "" { - return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{ - "code": errors.CodeUnauthorized, - "message": "未提供认证令牌", - }) + return errors.New(errors.CodeMissingToken, "未提供认证令牌") } // 验证 token if config.TokenValidator == nil { - return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ - "code": errors.CodeInternalError, - "message": "认证验证器未配置", - }) + return errors.New(errors.CodeInternalError, "认证验证器未配置") } userID, userType, shopID, err := config.TokenValidator(token) if err != nil { - return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{ - "code": errors.CodeUnauthorized, - "message": "认证令牌无效", - }) + // 如果验证器返回的是 AppError，直接返回 + if appErr, ok := err.(*errors.AppError); ok { + return appErr + } + // 否则包装为 AppError + return errors.Wrap(errors.CodeInvalidToken, "认证令牌无效", err) } // 将用户信息设置到 context diff --git a/pkg/response/response.go b/pkg/response/response.go index 7409380..76876e6 100644 --- a/pkg/response/response.go +++ b/pkg/response/response.go @@ -25,16 +25,6 @@ func Success(c *fiber.Ctx, data any) error { }) } -// Error 返回错误响应 -func Error(c *fiber.Ctx, httpStatus int, code int, message string) error { - return c.Status(httpStatus).JSON(Response{ - Code: code, - Data: nil, - Message: message, - Timestamp: time.Now().Format(time.RFC3339), - }) -} - // SuccessWithMessage 返回带自定义消息的成功响应 func SuccessWithMessage(c *fiber.Ctx, data any, message string) error { return c.JSON(Response{ diff --git a/pkg/response/response_bench_test.go b/pkg/response/response_bench_test.go index 0ad87f3..cac857a 100644 --- a/pkg/response/response_bench_test.go +++ b/pkg/response/response_bench_test.go @@ -36,17 +36,8 @@ func BenchmarkSuccess(b *testing.B) { }) } -// BenchmarkError 测试错误响应性能 -func BenchmarkError(b *testing.B) { - app := fiber.New() - - b.ResetTimer() - for i := 0; i < b.N; i++ { - ctx := app.AcquireCtx(&fasthttp.RequestCtx{}) - _ = Error(ctx, 400, 1001, "无效的请求") - app.ReleaseCtx(ctx) - } -} +// BenchmarkError 基准测试已被删除 - Error() 函数已在重构中移除 +// 错误响应现在由全局 ErrorHandler 统一处理 // BenchmarkSuccessWithMessage 测试带自定义消息的成功响应性能 func BenchmarkSuccessWithMessage(b *testing.B) { diff --git a/pkg/response/response_test.go b/pkg/response/response_test.go index 5ec7778..b59a085 100644 --- a/pkg/response/response_test.go +++ b/pkg/response/response_test.go @@ -111,107 +111,9 @@ func TestSuccess(t *testing.T) { } } -// TestError 测试错误响应（T035） -func TestError(t *testing.T) { - tests := []struct { - name string - httpStatus int - code int - message string - }{ - { - name: "internal server error", - httpStatus: 500, - code: errors.CodeInternalError, - message: "Internal server error occurred", - }, - { - name: "missing token error", - httpStatus: 401, - code: errors.CodeMissingToken, - message: "Authentication token is missing", - }, - { - name: "invalid token error", - httpStatus: 401, - code: errors.CodeInvalidToken, - message: "Token is invalid or expired", - }, - { - name: "rate limit error", - httpStatus: 429, - code: errors.CodeTooManyRequests, - message: "Too many requests, please try again later", - }, - { - name: "service unavailable error", - httpStatus: 503, - code: errors.CodeAuthServiceUnavailable, - message: "Authentication service is currently unavailable", - }, - { - name: "bad request error", - httpStatus: 400, - code: 2000, - message: "Invalid request parameters", - }, - } - - for _, tt := range tests { - t.Run(tt.name, func(t *testing.T) { - app := fiber.New() - app.Get("/test", func(c *fiber.Ctx) error { - return Error(c, tt.httpStatus, tt.code, tt.message) - }) - - req := httptest.NewRequest("GET", "/test", nil) - resp, err := app.Test(req) - if err != nil { - t.Fatalf("Failed to execute request: %v", err) - } - defer func() { _ = resp.Body.Close() }() - - // 验证 HTTP 状态码 - if resp.StatusCode != tt.httpStatus { - t.Errorf("Expected status code %d, got %d", tt.httpStatus, resp.StatusCode) - } - - // 验证响应头 - if resp.Header.Get("Content-Type") != "application/json" { - t.Errorf("Expected Content-Type application/json, got %s", resp.Header.Get("Content-Type")) - } - - // 解析响应体 - body, err := io.ReadAll(resp.Body) - if err != nil { - t.Fatalf("Failed to read response body: %v", err) - } - - var response Response - if err := sonic.Unmarshal(body, &response); err != nil { - t.Fatalf("Failed to unmarshal response: %v", err) - } - - // 验证响应结构 - if response.Code != tt.code { - t.Errorf("Expected code %d, got %d", tt.code, response.Code) - } - - if response.Message != tt.message { - t.Errorf("Expected message '%s', got '%s'", tt.message, response.Message) - } - - if response.Data != nil { - t.Errorf("Expected data to be nil in error response, got %v", response.Data) - } - - // 验证时间戳格式 RFC3339 - if _, err := time.Parse(time.RFC3339, response.Timestamp); err != nil { - t.Errorf("Timestamp is not in RFC3339 format: %s", response.Timestamp) - } - }) - } -} +// TestError 测试已被删除 - Error() 函数已在重构中移除 +// 错误响应现在由全局 ErrorHandler 统一处理 +// 相关测试已迁移到 pkg/errors/handler_test.go // TestSuccessWithMessage 测试带自定义消息的成功响应（T034） func TestSuccessWithMessage(t *testing.T) { @@ -413,10 +315,8 @@ func TestMultipleResponses(t *testing.T) { callCount := 0 app.Get("/test", func(c *fiber.Ctx) error { callCount++ - if callCount%2 == 0 { - return Success(c, map[string]int{"count": callCount}) - } - return Error(c, 500, errors.CodeInternalError, "error occurred") + // 只返回成功响应，因为 Error() 函数已被删除 + return Success(c, map[string]int{"count": callCount}) }) // 发送多个请求 diff --git a/tests/integration/account_test.go b/tests/integration/account_test.go index 1e8a057..6a316fd 100644 --- a/tests/integration/account_test.go +++ b/tests/integration/account_test.go @@ -21,6 +21,7 @@ import ( "gorm.io/gorm" "gorm.io/gorm/logger" + "github.com/break/junhong_cmp_fiber/internal/bootstrap" "github.com/break/junhong_cmp_fiber/internal/handler" "github.com/break/junhong_cmp_fiber/internal/model" "github.com/break/junhong_cmp_fiber/internal/routes" @@ -116,8 +117,8 @@ func setupTestEnv(t *testing.T) *testEnv { }) // 注册路由 - services := &routes.Services{ - AccountHandler: accountHandler, + services := &bootstrap.Handlers{ + Account: accountHandler, } routes.RegisterRoutes(app, services) diff --git a/tests/integration/api_regression_test.go b/tests/integration/api_regression_test.go index 5d8a598..2e41e14 100644 --- a/tests/integration/api_regression_test.go +++ b/tests/integration/api_regression_test.go @@ -19,6 +19,7 @@ import ( "gorm.io/gorm" "gorm.io/gorm/logger" + "github.com/break/junhong_cmp_fiber/internal/bootstrap" "github.com/break/junhong_cmp_fiber/internal/handler" "github.com/break/junhong_cmp_fiber/internal/model" "github.com/break/junhong_cmp_fiber/internal/routes" @@ -126,10 +127,10 @@ func setupRegressionTestEnv(t *testing.T) *regressionTestEnv { }) // 注册所有路由 - services := &routes.Services{ - AccountHandler: accountHandler, - RoleHandler: roleHandler, - PermissionHandler: permHandler, + services := &bootstrap.Handlers{ + Account: accountHandler, + Role: roleHandler, + Permission: permHandler, } routes.RegisterRoutes(app, services) diff --git a/tests/integration/auth_test.go b/tests/integration/auth_test.go index 1f1daa4..731eb50 100644 --- a/tests/integration/auth_test.go +++ b/tests/integration/auth_test.go @@ -7,10 +7,10 @@ import ( "testing" "time" - "github.com/break/junhong_cmp_fiber/internal/middleware" "github.com/break/junhong_cmp_fiber/pkg/constants" "github.com/break/junhong_cmp_fiber/pkg/errors" "github.com/break/junhong_cmp_fiber/pkg/logger" + "github.com/break/junhong_cmp_fiber/pkg/middleware" "github.com/break/junhong_cmp_fiber/pkg/response" "github.com/break/junhong_cmp_fiber/pkg/validator" "github.com/gofiber/fiber/v2" @@ -52,7 +52,16 @@ func setupAuthTestApp(t *testing.T, rdb *redis.Client) *fiber.App { // Add authentication middleware tokenValidator := validator.NewTokenValidator(rdb, logger.GetAppLogger()) - app.Use(middleware.KeyAuth(tokenValidator, logger.GetAppLogger())) + app.Use(middleware.Auth(middleware.AuthConfig{ + TokenValidator: func(token string) (uint, int, uint, error) { + _, err := tokenValidator.Validate(token) + if err != nil { + return 0, 0, 0, err + } + // 测试中简化处理：userID 设为 1，userType 设为普通用户 + return 1, 0, 0, nil + }, + })) // Add protected test routes app.Get("/api/v1/test", func(c *fiber.Ctx) error { @@ -342,14 +351,23 @@ func TestKeyAuthMiddleware_UserIDPropagation(t *testing.T) { // Add authentication middleware tokenValidator := validator.NewTokenValidator(rdb, logger.GetAppLogger()) - app.Use(middleware.KeyAuth(tokenValidator, logger.GetAppLogger())) + app.Use(middleware.Auth(middleware.AuthConfig{ + TokenValidator: func(token string) (uint, int, uint, error) { + _, err := tokenValidator.Validate(token) + if err != nil { + return 0, 0, 0, err + } + // 测试中简化处理：userID 设为 1，userType 设为普通用户 + return 1, 0, 0, nil + }, + })) // Add test route that checks user ID - var capturedUserID string + var capturedUserID uint app.Get("/api/v1/check-user", func(c *fiber.Ctx) error { - userID, ok := c.Locals(constants.ContextKeyUserID).(string) + userID, ok := c.Locals(constants.ContextKeyUserID).(uint) if !ok { - return response.Error(c, 500, errors.CodeInternalError, "User ID not found in context") + return errors.New(errors.CodeInternalError, "User ID not found in context") } capturedUserID = userID return response.Success(c, fiber.Map{ diff --git a/tests/integration/data_permission_test.go b/tests/integration/data_permission_test.go deleted file mode 100644 index 062d7eb..0000000 --- a/tests/integration/data_permission_test.go +++ /dev/null @@ -1,325 +0,0 @@ -package integration - -import ( - "context" - "testing" - - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/require" - - "github.com/break/junhong_cmp_fiber/internal/model" - "github.com/break/junhong_cmp_fiber/internal/store/postgres" - "github.com/break/junhong_cmp_fiber/pkg/constants" - "github.com/break/junhong_cmp_fiber/pkg/middleware" -) - -// TestDataPermission_HierarchicalFiltering 测试层级数据权限过滤 -func TestDataPermission_HierarchicalFiltering(t *testing.T) { - store, cleanup := setupTestDB(t) - defer cleanup() - - ctx := context.Background() - db := store.DB() - - // 创建层级结构: A -> B -> C - accountA := &model.Account{ - Username: "user_a", - Phone: "13800000001", - Password: "hashed_password", - UserType: constants.UserTypePlatform, - Status: constants.StatusEnabled, - Creator: 1, - Updater: 1, - } - require.NoError(t, db.Create(accountA).Error) - - shopID := uint(100) - accountA.ShopID = &shopID - require.NoError(t, db.Save(accountA).Error) - - accountB := &model.Account{ - Username: "user_b", - Phone: "13800000002", - Password: "hashed_password", - UserType: constants.UserTypeAgent, - ParentID: &accountA.ID, - ShopID: &shopID, - Status: constants.StatusEnabled, - Creator: 1, - Updater: 1, - } - require.NoError(t, db.Create(accountB).Error) - - accountC := &model.Account{ - Username: "user_c", - Phone: "13800000003", - Password: "hashed_password", - UserType: constants.UserTypeEnterprise, - ParentID: &accountB.ID, - ShopID: &shopID, - Status: constants.StatusEnabled, - Creator: 1, - Updater: 1, - } - require.NoError(t, db.Create(accountC).Error) - - // 创建测试数据表 - type TestData struct { - ID uint `gorm:"primarykey"` - Name string - OwnerID uint - ShopID uint - } - require.NoError(t, db.AutoMigrate(&TestData{})) - - // 插入测试数据 - testData := []TestData{ - {Name: "data_a", OwnerID: accountA.ID, ShopID: 100}, - {Name: "data_b", OwnerID: accountB.ID, ShopID: 100}, - {Name: "data_c", OwnerID: accountC.ID, ShopID: 100}, - {Name: "data_other", OwnerID: 999, ShopID: 100}, - } - require.NoError(t, db.Create(&testData).Error) - - // 创建 AccountStore 用于递归查询 - accountStore := postgres.NewAccountStore(db, nil) // Redis 可选 - - t.Run("A 用户可以看到 A、B、C 的数据", func(t *testing.T) { - ctxWithA := middleware.SetUserContext(ctx, accountA.ID, constants.UserTypePlatform, 100) - var results []TestData - err := db.WithContext(ctxWithA). - Scopes(postgres.DataPermissionScope(ctxWithA, accountStore)). - Find(&results).Error - require.NoError(t, err) - assert.Len(t, results, 3) - }) - - t.Run("B 用户可以看到 B、C 的数据", func(t *testing.T) { - ctxWithB := middleware.SetUserContext(ctx, accountB.ID, constants.UserTypeAgent, 100) - var results []TestData - err := db.WithContext(ctxWithB). - Scopes(postgres.DataPermissionScope(ctxWithB, accountStore)). - Find(&results).Error - require.NoError(t, err) - assert.Len(t, results, 2) - }) - - t.Run("C 用户只能看到自己的数据", func(t *testing.T) { - ctxWithC := middleware.SetUserContext(ctx, accountC.ID, constants.UserTypeEnterprise, 100) - var results []TestData - err := db.WithContext(ctxWithC). - Scopes(postgres.DataPermissionScope(ctxWithC, accountStore)). - Find(&results).Error - require.NoError(t, err) - assert.Len(t, results, 1) - assert.Equal(t, "data_c", results[0].Name) - }) -} - -// TestDataPermission_WithoutDataFilter 测试 WithoutDataFilter 选项 -func TestDataPermission_WithoutDataFilter(t *testing.T) { - store, cleanup := setupTestDB(t) - defer cleanup() - - ctx := context.Background() - db := store.DB() - - // 创建测试账号 - shopID := uint(100) - accountA := &model.Account{ - Username: "user_a", - Phone: "13800000001", - Password: "hashed_password", - UserType: constants.UserTypePlatform, - ShopID: &shopID, - Status: constants.StatusEnabled, - Creator: 1, - Updater: 1, - } - require.NoError(t, db.Create(accountA).Error) - - // 创建测试数据表 - type TestData struct { - ID uint `gorm:"primarykey"` - Name string - OwnerID uint - ShopID uint - } - require.NoError(t, db.AutoMigrate(&TestData{})) - - // 插入测试数据 - testData := []TestData{ - {Name: "data_a", OwnerID: accountA.ID, ShopID: 100}, - {Name: "data_b", OwnerID: 999, ShopID: 100}, - {Name: "data_c", OwnerID: 888, ShopID: 200}, - } - require.NoError(t, db.Create(&testData).Error) - - // 创建 AccountStore - accountStore := postgres.NewAccountStore(db, nil) - - t.Run("正常查询应该过滤数据", func(t *testing.T) { - ctxWithA := middleware.SetUserContext(ctx, accountA.ID, constants.UserTypePlatform, 100) - var results []TestData - err := db.WithContext(ctxWithA). - Scopes(postgres.DataPermissionScope(ctxWithA, accountStore)). - Find(&results).Error - require.NoError(t, err) - assert.Len(t, results, 1) - }) - - t.Run("不带用户上下文时返回空数据", func(t *testing.T) { - var results []TestData - err := db.WithContext(ctx). - Scopes(postgres.DataPermissionScope(ctx, accountStore)). - Find(&results).Error - require.NoError(t, err) - assert.Len(t, results, 0) - }) -} - -// TestDataPermission_CrossShopIsolation 测试跨店铺数据隔离 -func TestDataPermission_CrossShopIsolation(t *testing.T) { - store, cleanup := setupTestDB(t) - defer cleanup() - - ctx := context.Background() - db := store.DB() - - // 创建两个不同店铺的账号 - shopID100 := uint(100) - accountA := &model.Account{ - Username: "user_shop100", - Phone: "13800000001", - Password: "hashed_password", - UserType: constants.UserTypePlatform, - ShopID: &shopID100, - Status: constants.StatusEnabled, - Creator: 1, - Updater: 1, - } - require.NoError(t, db.Create(accountA).Error) - - shopID200 := uint(200) - accountB := &model.Account{ - Username: "user_shop200", - Phone: "13800000002", - Password: "hashed_password", - UserType: constants.UserTypePlatform, - ShopID: &shopID200, - Status: constants.StatusEnabled, - Creator: 1, - Updater: 1, - } - require.NoError(t, db.Create(accountB).Error) - - // 创建测试数据表 - type TestData struct { - ID uint `gorm:"primarykey"` - Name string - OwnerID uint - ShopID uint - } - require.NoError(t, db.AutoMigrate(&TestData{})) - - // 插入不同店铺的数据 - testData := []TestData{ - {Name: "data_shop100_1", OwnerID: accountA.ID, ShopID: 100}, - {Name: "data_shop100_2", OwnerID: accountA.ID, ShopID: 100}, - {Name: "data_shop200_1", OwnerID: accountB.ID, ShopID: 200}, - {Name: "data_shop200_2", OwnerID: accountB.ID, ShopID: 200}, - } - require.NoError(t, db.Create(&testData).Error) - - // 创建 AccountStore - accountStore := postgres.NewAccountStore(db, nil) - - t.Run("店铺 100 用户只能看到店铺 100 的数据", func(t *testing.T) { - ctxWithA := middleware.SetUserContext(ctx, accountA.ID, constants.UserTypePlatform, 100) - var results []TestData - err := db.WithContext(ctxWithA). - Scopes(postgres.DataPermissionScope(ctxWithA, accountStore)). - Find(&results).Error - require.NoError(t, err) - assert.Len(t, results, 2) - for _, r := range results { - assert.Equal(t, uint(100), r.ShopID) - } - }) - - t.Run("店铺 200 用户只能看到店铺 200 的数据", func(t *testing.T) { - ctxWithB := middleware.SetUserContext(ctx, accountB.ID, constants.UserTypePlatform, 200) - var results []TestData - err := db.WithContext(ctxWithB). - Scopes(postgres.DataPermissionScope(ctxWithB, accountStore)). - Find(&results).Error - require.NoError(t, err) - assert.Len(t, results, 2) - for _, r := range results { - assert.Equal(t, uint(200), r.ShopID) - } - }) - - t.Run("店铺 100 用户看不到店铺 200 的数据", func(t *testing.T) { - ctxWithA := middleware.SetUserContext(ctx, accountA.ID, constants.UserTypePlatform, 100) - var results []TestData - err := db.WithContext(ctxWithA). - Scopes(postgres.DataPermissionScope(ctxWithA, accountStore)). - Where("shop_id = ?", 200). // 尝试查询店铺 200 的数据 - Find(&results).Error - require.NoError(t, err) - assert.Len(t, results, 0, "不应该看到其他店铺的数据") - }) -} - -// TestDataPermission_RootUserBypass 测试 root 用户跳过数据权限过滤 -func TestDataPermission_RootUserBypass(t *testing.T) { - store, cleanup := setupTestDB(t) - defer cleanup() - - ctx := context.Background() - db := store.DB() - - // 创建 root 用户 - rootUser := &model.Account{ - Username: "root_user", - Phone: "13800000000", - Password: "hashed_password", - UserType: constants.UserTypeRoot, - Status: constants.StatusEnabled, - Creator: 1, - Updater: 1, - } - require.NoError(t, db.Create(rootUser).Error) - - // 创建测试数据表 - type TestData struct { - ID uint `gorm:"primarykey"` - Name string - OwnerID uint - ShopID uint - } - require.NoError(t, db.AutoMigrate(&TestData{})) - - // 插入不同店铺、不同用户的数据 - testData := []TestData{ - {Name: "data_1", OwnerID: 1, ShopID: 100}, - {Name: "data_2", OwnerID: 2, ShopID: 200}, - {Name: "data_3", OwnerID: 3, ShopID: 300}, - {Name: "data_4", OwnerID: 4, ShopID: 400}, - } - require.NoError(t, db.Create(&testData).Error) - - // 创建 AccountStore - accountStore := postgres.NewAccountStore(db, nil) - - t.Run("root 用户可以看到所有数据", func(t *testing.T) { - ctxWithRoot := middleware.SetUserContext(ctx, rootUser.ID, constants.UserTypeRoot, 100) - var results []TestData - err := db.WithContext(ctxWithRoot). - Scopes(postgres.DataPermissionScope(ctxWithRoot, accountStore)). - Find(&results).Error - require.NoError(t, err) - assert.Len(t, results, 4, "root 用户应该看到所有数据") - }) -} diff --git a/tests/integration/database_test.go b/tests/integration/database_test.go deleted file mode 100644 index fbdb05b..0000000 --- a/tests/integration/database_test.go +++ /dev/null @@ -1,489 +0,0 @@ -package integration - -import ( - "context" - "fmt" - "os" - "path/filepath" - "testing" - "time" - - "github.com/break/junhong_cmp_fiber/internal/model" - "github.com/break/junhong_cmp_fiber/internal/store/postgres" - "github.com/break/junhong_cmp_fiber/pkg/constants" - "github.com/golang-migrate/migrate/v4" - _ "github.com/golang-migrate/migrate/v4/database/postgres" - _ "github.com/golang-migrate/migrate/v4/source/file" - _ "github.com/lib/pq" - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/require" - "github.com/testcontainers/testcontainers-go" - testcontainers_postgres "github.com/testcontainers/testcontainers-go/modules/postgres" - "github.com/testcontainers/testcontainers-go/wait" - "go.uber.org/zap" - postgresDriver "gorm.io/driver/postgres" - "gorm.io/gorm" - "gorm.io/gorm/logger" -) - -// TestMain 设置测试环境 -func TestMain(m *testing.M) { - code := m.Run() - os.Exit(code) -} - -// setupTestDB 启动 PostgreSQL 容器并使用迁移脚本初始化数据库 -func setupTestDB(t *testing.T) (*postgres.Store, func()) { - ctx := context.Background() - - // 启动 PostgreSQL 容器 - postgresContainer, err := testcontainers_postgres.RunContainer(ctx, - testcontainers.WithImage("postgres:14-alpine"), - testcontainers_postgres.WithDatabase("testdb"), - testcontainers_postgres.WithUsername("postgres"), - testcontainers_postgres.WithPassword("password"), - testcontainers.WithWaitStrategy( - wait.ForLog("database system is ready to accept connections"). - WithOccurrence(2). - WithStartupTimeout(30*time.Second), - ), - ) - require.NoError(t, err, "启动 PostgreSQL 容器失败") - - // 获取连接字符串 - connStr, err := postgresContainer.ConnectionString(ctx, "sslmode=disable") - require.NoError(t, err, "获取数据库连接字符串失败") - - // 应用数据库迁移 - migrationsPath := getMigrationsPath(t) - m, err := migrate.New( - fmt.Sprintf("file://%s", migrationsPath), - connStr, - ) - require.NoError(t, err, "创建迁移实例失败") - - // 执行向上迁移 - err = m.Up() - require.NoError(t, err, "执行数据库迁移失败") - - // 连接数据库 - db, err := gorm.Open(postgresDriver.Open(connStr), &gorm.Config{ - Logger: logger.Default.LogMode(logger.Silent), - }) - require.NoError(t, err, "连接数据库失败") - - // 创建测试 logger - testLogger := zap.NewNop() - store := postgres.NewStore(db, testLogger) - - // 返回清理函数 - cleanup := func() { - // 执行向下迁移清理数据 - if err := m.Down(); err != nil && err != migrate.ErrNoChange { - t.Logf("清理迁移失败: %v", err) - } - _, _ = m.Close() - - sqlDB, _ := db.DB() - if sqlDB != nil { - _ = sqlDB.Close() - } - if err := postgresContainer.Terminate(ctx); err != nil { - t.Logf("终止容器失败: %v", err) - } - } - - return store, cleanup -} - -// getMigrationsPath 获取迁移文件路径 -func getMigrationsPath(t *testing.T) string { - // 获取项目根目录 - wd, err := os.Getwd() - require.NoError(t, err, "获取工作目录失败") - - // 从测试目录向上找到项目根目录 - migrationsPath := filepath.Join(wd, "..", "..", "migrations") - - // 验证迁移目录存在 - _, err = os.Stat(migrationsPath) - require.NoError(t, err, fmt.Sprintf("迁移目录不存在: %s", migrationsPath)) - - return migrationsPath -} - -// TestUserCRUD 测试用户 CRUD 操作 -func TestUserCRUD(t *testing.T) { - store, cleanup := setupTestDB(t) - defer cleanup() - - ctx := context.Background() - - t.Run("创建用户", func(t *testing.T) { - user := &model.User{ - Username: "testuser", - Email: "test@example.com", - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - - err := store.User.Create(ctx, user) - assert.NoError(t, err) - assert.NotZero(t, user.ID) - assert.NotZero(t, user.CreatedAt) - assert.NotZero(t, user.UpdatedAt) - }) - - t.Run("根据ID查询用户", func(t *testing.T) { - // 创建测试用户 - user := &model.User{ - Username: "queryuser", - Email: "query@example.com", - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - err := store.User.Create(ctx, user) - require.NoError(t, err) - - // 查询用户 - found, err := store.User.GetByID(ctx, user.ID) - assert.NoError(t, err) - assert.Equal(t, user.Username, found.Username) - assert.Equal(t, user.Email, found.Email) - assert.Equal(t, constants.UserStatusActive, found.Status) - }) - - t.Run("根据用户名查询用户", func(t *testing.T) { - // 创建测试用户 - user := &model.User{ - Username: "findbyname", - Email: "findbyname@example.com", - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - err := store.User.Create(ctx, user) - require.NoError(t, err) - - // 根据用户名查询 - found, err := store.User.GetByUsername(ctx, "findbyname") - assert.NoError(t, err) - assert.Equal(t, user.ID, found.ID) - assert.Equal(t, user.Email, found.Email) - }) - - t.Run("更新用户", func(t *testing.T) { - // 创建测试用户 - user := &model.User{ - Username: "updateuser", - Email: "update@example.com", - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - err := store.User.Create(ctx, user) - require.NoError(t, err) - - // 更新用户 - user.Email = "newemail@example.com" - user.Status = constants.UserStatusInactive - err = store.User.Update(ctx, user) - assert.NoError(t, err) - - // 验证更新 - found, err := store.User.GetByID(ctx, user.ID) - assert.NoError(t, err) - assert.Equal(t, "newemail@example.com", found.Email) - assert.Equal(t, constants.UserStatusInactive, found.Status) - }) - - t.Run("列表查询用户", func(t *testing.T) { - // 创建多个测试用户 - for i := 1; i <= 5; i++ { - user := &model.User{ - Username: fmt.Sprintf("listuser%d", i), - Email: fmt.Sprintf("list%d@example.com", i), - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - err := store.User.Create(ctx, user) - require.NoError(t, err) - } - - // 列表查询 - users, total, err := store.User.List(ctx, 1, 3) - assert.NoError(t, err) - assert.GreaterOrEqual(t, len(users), 3) - assert.GreaterOrEqual(t, total, int64(5)) - }) - - t.Run("软删除用户", func(t *testing.T) { - // 创建测试用户 - user := &model.User{ - Username: "deleteuser", - Email: "delete@example.com", - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - err := store.User.Create(ctx, user) - require.NoError(t, err) - - // 软删除 - err = store.User.Delete(ctx, user.ID) - assert.NoError(t, err) - - // 验证已删除（查询应该找不到） - _, err = store.User.GetByID(ctx, user.ID) - assert.Error(t, err) - assert.Equal(t, gorm.ErrRecordNotFound, err) - }) -} - -// TestOrderCRUD 测试订单 CRUD 操作 -func TestOrderCRUD(t *testing.T) { - store, cleanup := setupTestDB(t) - defer cleanup() - - ctx := context.Background() - - // 创建测试用户 - user := &model.User{ - Username: "orderuser", - Email: "orderuser@example.com", - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - err := store.User.Create(ctx, user) - require.NoError(t, err) - - t.Run("创建订单", func(t *testing.T) { - order := &model.Order{ - OrderID: "ORD-001", - UserID: user.ID, - Amount: 10000, - Status: constants.OrderStatusPending, - Remark: "测试订单", - } - - err := store.Order.Create(ctx, order) - assert.NoError(t, err) - assert.NotZero(t, order.ID) - assert.NotZero(t, order.CreatedAt) - }) - - t.Run("根据ID查询订单", func(t *testing.T) { - // 创建测试订单 - order := &model.Order{ - OrderID: "ORD-002", - UserID: user.ID, - Amount: 20000, - Status: constants.OrderStatusPending, - } - err := store.Order.Create(ctx, order) - require.NoError(t, err) - - // 查询订单 - found, err := store.Order.GetByID(ctx, order.ID) - assert.NoError(t, err) - assert.Equal(t, order.OrderID, found.OrderID) - assert.Equal(t, order.Amount, found.Amount) - }) - - t.Run("根据订单号查询", func(t *testing.T) { - // 创建测试订单 - order := &model.Order{ - OrderID: "ORD-003", - UserID: user.ID, - Amount: 30000, - Status: constants.OrderStatusPending, - } - err := store.Order.Create(ctx, order) - require.NoError(t, err) - - // 根据订单号查询 - found, err := store.Order.GetByOrderID(ctx, "ORD-003") - assert.NoError(t, err) - assert.Equal(t, order.ID, found.ID) - }) - - t.Run("根据用户ID列表查询", func(t *testing.T) { - // 创建多个订单 - for i := 1; i <= 3; i++ { - order := &model.Order{ - OrderID: fmt.Sprintf("ORD-USER-%d", i), - UserID: user.ID, - Amount: int64(i * 10000), - Status: constants.OrderStatusPending, - } - err := store.Order.Create(ctx, order) - require.NoError(t, err) - } - - // 列表查询 - orders, total, err := store.Order.ListByUserID(ctx, user.ID, 1, 10) - assert.NoError(t, err) - assert.GreaterOrEqual(t, len(orders), 3) - assert.GreaterOrEqual(t, total, int64(3)) - }) - - t.Run("更新订单状态", func(t *testing.T) { - // 创建测试订单 - order := &model.Order{ - OrderID: "ORD-UPDATE", - UserID: user.ID, - Amount: 50000, - Status: constants.OrderStatusPending, - } - err := store.Order.Create(ctx, order) - require.NoError(t, err) - - // 更新状态 - now := time.Now() - order.Status = constants.OrderStatusPaid - order.PaidAt = &now - err = store.Order.Update(ctx, order) - assert.NoError(t, err) - - // 验证更新 - found, err := store.Order.GetByID(ctx, order.ID) - assert.NoError(t, err) - assert.Equal(t, constants.OrderStatusPaid, found.Status) - assert.NotNil(t, found.PaidAt) - }) - - t.Run("软删除订单", func(t *testing.T) { - // 创建测试订单 - order := &model.Order{ - OrderID: "ORD-DELETE", - UserID: user.ID, - Amount: 60000, - Status: constants.OrderStatusPending, - } - err := store.Order.Create(ctx, order) - require.NoError(t, err) - - // 软删除 - err = store.Order.Delete(ctx, order.ID) - assert.NoError(t, err) - - // 验证已删除 - _, err = store.Order.GetByID(ctx, order.ID) - assert.Error(t, err) - assert.Equal(t, gorm.ErrRecordNotFound, err) - }) -} - -// TestTransaction 测试事务功能 -func TestTransaction(t *testing.T) { - store, cleanup := setupTestDB(t) - defer cleanup() - - ctx := context.Background() - - t.Run("事务提交", func(t *testing.T) { - var userID uint - var orderID uint - - err := store.Transaction(ctx, func(tx *postgres.Store) error { - // 创建用户 - user := &model.User{ - Username: "txuser", - Email: "txuser@example.com", - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - if err := tx.User.Create(ctx, user); err != nil { - return err - } - userID = user.ID - - // 创建订单 - order := &model.Order{ - OrderID: "ORD-TX-001", - UserID: user.ID, - Amount: 10000, - Status: constants.OrderStatusPending, - } - if err := tx.Order.Create(ctx, order); err != nil { - return err - } - orderID = order.ID - - return nil - }) - - assert.NoError(t, err) - - // 验证用户和订单都已创建 - user, err := store.User.GetByID(ctx, userID) - assert.NoError(t, err) - assert.Equal(t, "txuser", user.Username) - - order, err := store.Order.GetByID(ctx, orderID) - assert.NoError(t, err) - assert.Equal(t, "ORD-TX-001", order.OrderID) - }) - - t.Run("事务回滚", func(t *testing.T) { - var userID uint - - err := store.Transaction(ctx, func(tx *postgres.Store) error { - // 创建用户 - user := &model.User{ - Username: "rollbackuser", - Email: "rollback@example.com", - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - if err := tx.User.Create(ctx, user); err != nil { - return err - } - userID = user.ID - - // 模拟错误，触发回滚 - return fmt.Errorf("模拟错误") - }) - - assert.Error(t, err) - assert.Equal(t, "模拟错误", err.Error()) - - // 验证用户未创建（已回滚） - _, err = store.User.GetByID(ctx, userID) - assert.Error(t, err) - assert.Equal(t, gorm.ErrRecordNotFound, err) - }) -} - -// TestConcurrentOperations 测试并发操作 -func TestConcurrentOperations(t *testing.T) { - store, cleanup := setupTestDB(t) - defer cleanup() - - ctx := context.Background() - - t.Run("并发创建用户", func(t *testing.T) { - concurrency := 10 - errChan := make(chan error, concurrency) - - for i := 0; i < concurrency; i++ { - go func(index int) { - user := &model.User{ - Username: fmt.Sprintf("concurrent%d", index), - Email: fmt.Sprintf("concurrent%d@example.com", index), - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - errChan <- store.User.Create(ctx, user) - }(i) - } - - // 收集结果 - successCount := 0 - for i := 0; i < concurrency; i++ { - err := <-errChan - if err == nil { - successCount++ - } - } - - assert.Equal(t, concurrency, successCount, "所有并发创建应该成功") - }) -} diff --git a/tests/integration/migration_test.go b/tests/integration/migration_test.go index 132dbdb..877d0ca 100644 --- a/tests/integration/migration_test.go +++ b/tests/integration/migration_test.go @@ -8,6 +8,7 @@ import ( "testing" "time" + "github.com/break/junhong_cmp_fiber/tests/testutils" "github.com/golang-migrate/migrate/v4" _ "github.com/golang-migrate/migrate/v4/database/postgres" _ "github.com/golang-migrate/migrate/v4/source/file" @@ -49,7 +50,7 @@ func TestMigration_UpAndDown(t *testing.T) { require.NoError(t, err, "获取数据库连接字符串失败") // 应用数据库迁移 - migrationsPath := getMigrationsPath(t) + migrationsPath := testutils.GetMigrationsPath() m, err := migrate.New( fmt.Sprintf("file://%s", migrationsPath), connStr, @@ -135,7 +136,7 @@ func TestMigration_UpAndDown(t *testing.T) { // TestMigration_NoForeignKeys 验证迁移脚本不包含外键约束 func TestMigration_NoForeignKeys(t *testing.T) { // 获取迁移目录 - migrationsPath := getMigrationsPath(t) + migrationsPath := testutils.GetMigrationsPath() // 读取所有迁移文件 files, err := filepath.Glob(filepath.Join(migrationsPath, "*.up.sql")) @@ -187,7 +188,7 @@ func TestMigration_SoftDeleteSupport(t *testing.T) { require.NoError(t, err, "获取数据库连接字符串失败") // 应用迁移 - migrationsPath := getMigrationsPath(t) + migrationsPath := testutils.GetMigrationsPath() m, err := migrate.New( fmt.Sprintf("file://%s", migrationsPath), connStr, diff --git a/tests/integration/permission_test.go b/tests/integration/permission_test.go index 92fe3d1..ad95a24 100644 --- a/tests/integration/permission_test.go +++ b/tests/integration/permission_test.go @@ -19,6 +19,7 @@ import ( "gorm.io/gorm" "gorm.io/gorm/logger" + "github.com/break/junhong_cmp_fiber/internal/bootstrap" "github.com/break/junhong_cmp_fiber/internal/handler" "github.com/break/junhong_cmp_fiber/internal/model" "github.com/break/junhong_cmp_fiber/internal/routes" @@ -90,8 +91,8 @@ func setupPermTestEnv(t *testing.T) *permTestEnv { }) // 注册路由 - services := &routes.Services{ - PermissionHandler: permHandler, + services := &bootstrap.Handlers{ + Permission: permHandler, } routes.RegisterRoutes(app, services) diff --git a/tests/integration/role_test.go b/tests/integration/role_test.go index 4554efb..41e74af 100644 --- a/tests/integration/role_test.go +++ b/tests/integration/role_test.go @@ -21,6 +21,7 @@ import ( "gorm.io/gorm" "gorm.io/gorm/logger" + "github.com/break/junhong_cmp_fiber/internal/bootstrap" "github.com/break/junhong_cmp_fiber/internal/handler" "github.com/break/junhong_cmp_fiber/internal/model" "github.com/break/junhong_cmp_fiber/internal/routes" @@ -116,8 +117,8 @@ func setupRoleTestEnv(t *testing.T) *roleTestEnv { }) // 注册路由 - services := &routes.Services{ - RoleHandler: roleHandler, + services := &bootstrap.Handlers{ + Role: roleHandler, } routes.RegisterRoutes(app, services) diff --git a/tests/testutils/helpers.go b/tests/testutils/helpers.go new file mode 100644 index 0000000..0964192 --- /dev/null +++ b/tests/testutils/helpers.go @@ -0,0 +1,39 @@ +package testutils + +import ( + "path/filepath" + "runtime" + "testing" + + "gorm.io/gorm" +) + +// SetupTestDBWithStore 设置测试数据库并返回 AccountStore 和 cleanup 函数 +// 用于需要 store 接口的集成测试 +func SetupTestDBWithStore(t *testing.T) (*gorm.DB, func()) { + t.Helper() + + db, redisClient := SetupTestDB(t) + + cleanup := func() { + TeardownTestDB(t, db, redisClient) + } + + return db, cleanup +} + +// GetMigrationsPath 获取数据库迁移文件的路径 +// 返回项目根目录下的 migrations 目录路径 +func GetMigrationsPath() string { + // 获取当前文件路径 + _, filename, _, ok := runtime.Caller(0) + if !ok { + panic("无法获取当前文件路径") + } + + // 从 tests/testutils/helpers.go 向上两级到项目根目录 + projectRoot := filepath.Join(filepath.Dir(filename), "..", "..") + migrationsPath := filepath.Join(projectRoot, "migrations") + + return migrationsPath +} diff --git a/tests/unit/data_permission_scope_test.go b/tests/unit/data_permission_scope_test.go deleted file mode 100644 index 8716b92..0000000 --- a/tests/unit/data_permission_scope_test.go +++ /dev/null @@ -1,303 +0,0 @@ -package unit - -import ( - "context" - "testing" - - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/require" - - "github.com/break/junhong_cmp_fiber/internal/model" - "github.com/break/junhong_cmp_fiber/internal/store/postgres" - "github.com/break/junhong_cmp_fiber/pkg/constants" - "github.com/break/junhong_cmp_fiber/pkg/middleware" - "github.com/break/junhong_cmp_fiber/tests/testutils" -) - -// TestDataPermissionScope_RootUser 测试 root 用户跳过数据权限过滤 -func TestDataPermissionScope_RootUser(t *testing.T) { - db, redisClient := testutils.SetupTestDB(t) - defer testutils.TeardownTestDB(t, db, redisClient) - - accountStore := postgres.NewAccountStore(db, redisClient) - ctx := context.Background() - - // 创建 root 用户 - rootUser := &model.Account{ - Username: "root_user", - Phone: "13800000000", - Password: "hashed_password", - UserType: constants.UserTypeRoot, - Status: constants.StatusEnabled, - Creator: 1, - Updater: 1, - } - require.NoError(t, db.Create(rootUser).Error) - - // 创建测试数据表（模拟业务表） - type TestData struct { - ID uint `gorm:"primarykey"` - Name string - OwnerID uint - ShopID uint - } - require.NoError(t, db.AutoMigrate(&TestData{})) - - // 插入测试数据（不同的 owner_id 和 shop_id） - testData := []TestData{ - {Name: "data1", OwnerID: 1, ShopID: 100}, - {Name: "data2", OwnerID: 2, ShopID: 200}, - {Name: "data3", OwnerID: 3, ShopID: 300}, - } - require.NoError(t, db.Create(&testData).Error) - - // 设置 root 用户上下文 - ctxWithRoot := middleware.SetUserContext(ctx, rootUser.ID, constants.UserTypeRoot, 100) - - // 查询（应该返回所有数据，不过滤） - var results []TestData - err := db.WithContext(ctxWithRoot). - Scopes(postgres.DataPermissionScope(ctxWithRoot, accountStore)). - Find(&results).Error - require.NoError(t, err) - assert.Len(t, results, 3, "root 用户应该看到所有数据") -} - -// TestDataPermissionScope_NormalUser 测试普通用户数据权限过滤 -func TestDataPermissionScope_NormalUser(t *testing.T) { - db, redisClient := testutils.SetupTestDB(t) - defer testutils.TeardownTestDB(t, db, redisClient) - - accountStore := postgres.NewAccountStore(db, redisClient) - ctx := context.Background() - - // 创建账号层级: A -> B - accountA := &model.Account{ - Username: "user_a", - Phone: "13800000001", - Password: "hashed_password", - UserType: constants.UserTypePlatform, - Status: constants.StatusEnabled, - Creator: 1, - Updater: 1, - } - require.NoError(t, db.Create(accountA).Error) - - shopIDA := uint(100) - accountA.ShopID = &shopIDA - require.NoError(t, db.Save(accountA).Error) - - accountB := &model.Account{ - Username: "user_b", - Phone: "13800000002", - Password: "hashed_password", - UserType: constants.UserTypeAgent, - ParentID: &accountA.ID, - Status: constants.StatusEnabled, - Creator: 1, - Updater: 1, - } - require.NoError(t, db.Create(accountB).Error) - - shopIDB := uint(100) - accountB.ShopID = &shopIDB - require.NoError(t, db.Save(accountB).Error) - - // 创建测试数据表 - type TestData struct { - ID uint `gorm:"primarykey"` - Name string - OwnerID uint - ShopID uint - } - require.NoError(t, db.AutoMigrate(&TestData{})) - - // 插入测试数据 - testData := []TestData{ - {Name: "data_a", OwnerID: accountA.ID, ShopID: 100}, // A 的数据 - {Name: "data_b", OwnerID: accountB.ID, ShopID: 100}, // B 的数据 - {Name: "data_c", OwnerID: 999, ShopID: 100}, // 其他用户数据（同店铺） - {Name: "data_d", OwnerID: accountA.ID, ShopID: 200}, // A 的数据（不同店铺） - } - require.NoError(t, db.Create(&testData).Error) - - // A 登录查询（应该看到 A 和 B 的数据，同店铺） - ctxWithA := middleware.SetUserContext(ctx, accountA.ID, constants.UserTypePlatform, 100) - var resultsA []TestData - err := db.WithContext(ctxWithA). - Scopes(postgres.DataPermissionScope(ctxWithA, accountStore)). - Find(&resultsA).Error - require.NoError(t, err) - assert.Len(t, resultsA, 2, "A 应该看到自己和下级 B 的数据") - - // B 登录查询（只能看到自己的数据） - ctxWithB := middleware.SetUserContext(ctx, accountB.ID, constants.UserTypeAgent, 100) - var resultsB []TestData - err = db.WithContext(ctxWithB). - Scopes(postgres.DataPermissionScope(ctxWithB, accountStore)). - Find(&resultsB).Error - require.NoError(t, err) - assert.Len(t, resultsB, 1, "B 只能看到自己的数据") - assert.Equal(t, "data_b", resultsB[0].Name) -} - -// TestDataPermissionScope_ShopIsolation 测试店铺隔离 -func TestDataPermissionScope_ShopIsolation(t *testing.T) { - db, redisClient := testutils.SetupTestDB(t) - defer testutils.TeardownTestDB(t, db, redisClient) - - accountStore := postgres.NewAccountStore(db, redisClient) - ctx := context.Background() - - // 创建两个账号（同一层级，不同店铺） - shopID100 := uint(100) - accountA := &model.Account{ - Username: "user_a", - Phone: "13800000001", - Password: "hashed_password", - UserType: constants.UserTypePlatform, - ShopID: &shopID100, - Status: constants.StatusEnabled, - Creator: 1, - Updater: 1, - } - require.NoError(t, db.Create(accountA).Error) - - shopID200 := uint(200) - accountB := &model.Account{ - Username: "user_b", - Phone: "13800000002", - Password: "hashed_password", - UserType: constants.UserTypePlatform, - ShopID: &shopID200, - Status: constants.StatusEnabled, - Creator: 1, - Updater: 1, - } - require.NoError(t, db.Create(accountB).Error) - - // 创建测试数据表 - type TestData struct { - ID uint `gorm:"primarykey"` - Name string - OwnerID uint - ShopID uint - } - require.NoError(t, db.AutoMigrate(&TestData{})) - - // 插入测试数据 - testData := []TestData{ - {Name: "data_shop100", OwnerID: accountA.ID, ShopID: 100}, - {Name: "data_shop200", OwnerID: accountB.ID, ShopID: 200}, - } - require.NoError(t, db.Create(&testData).Error) - - // A 登录查询（只能看到店铺 100 的数据） - ctxWithA := middleware.SetUserContext(ctx, accountA.ID, constants.UserTypePlatform, 100) - var resultsA []TestData - err := db.WithContext(ctxWithA). - Scopes(postgres.DataPermissionScope(ctxWithA, accountStore)). - Find(&resultsA).Error - require.NoError(t, err) - assert.Len(t, resultsA, 1, "A 只能看到店铺 100 的数据") - assert.Equal(t, "data_shop100", resultsA[0].Name) - - // B 登录查询（只能看到店铺 200 的数据） - ctxWithB := middleware.SetUserContext(ctx, accountB.ID, constants.UserTypePlatform, 200) - var resultsB []TestData - err = db.WithContext(ctxWithB). - Scopes(postgres.DataPermissionScope(ctxWithB, accountStore)). - Find(&resultsB).Error - require.NoError(t, err) - assert.Len(t, resultsB, 1, "B 只能看到店铺 200 的数据") - assert.Equal(t, "data_shop200", resultsB[0].Name) -} - -// TestDataPermissionScope_NoUserContext 测试无用户上下文时不过滤 -func TestDataPermissionScope_NoUserContext(t *testing.T) { - db, redisClient := testutils.SetupTestDB(t) - defer testutils.TeardownTestDB(t, db, redisClient) - - accountStore := postgres.NewAccountStore(db, redisClient) - ctx := context.Background() - - // 创建测试数据表 - type TestData struct { - ID uint `gorm:"primarykey"` - Name string - OwnerID uint - ShopID uint - } - require.NoError(t, db.AutoMigrate(&TestData{})) - - // 插入测试数据 - testData := []TestData{ - {Name: "data1", OwnerID: 1, ShopID: 100}, - {Name: "data2", OwnerID: 2, ShopID: 200}, - } - require.NoError(t, db.Create(&testData).Error) - - // 使用没有用户信息的上下文查询（不过滤，可能是系统任务） - var results []TestData - err := db.WithContext(ctx). - Scopes(postgres.DataPermissionScope(ctx, accountStore)). - Find(&results).Error - require.NoError(t, err) - assert.Len(t, results, 0, "无用户上下文时应该返回空数据（根据 scopes.go 的实现）") -} - -// TestDataPermissionScope_ErrorHandling 测试查询下级 ID 失败时的降级策略 -func TestDataPermissionScope_ErrorHandling(t *testing.T) { - db, redisClient := testutils.SetupTestDB(t) - defer testutils.TeardownTestDB(t, db, redisClient) - - accountStore := postgres.NewAccountStore(db, redisClient) - ctx := context.Background() - - // 创建测试账号 - accountA := &model.Account{ - Username: "user_a", - Phone: "13800000001", - Password: "hashed_password", - UserType: constants.UserTypePlatform, - Status: constants.StatusEnabled, - Creator: 1, - Updater: 1, - } - require.NoError(t, db.Create(accountA).Error) - - shopIDA := uint(100) - accountA.ShopID = &shopIDA - require.NoError(t, db.Save(accountA).Error) - - // 创建测试数据表 - type TestData struct { - ID uint `gorm:"primarykey"` - Name string - OwnerID uint - ShopID uint - } - require.NoError(t, db.AutoMigrate(&TestData{})) - - // 插入测试数据 - testData := []TestData{ - {Name: "data_a", OwnerID: accountA.ID, ShopID: 100}, - {Name: "data_b", OwnerID: 999, ShopID: 100}, - } - require.NoError(t, db.Create(&testData).Error) - - // 关闭 Redis 连接以模拟错误（递归查询失败） - redisClient.Close() - - // 使用 A 的上下文查询（降级策略：只返回自己的数据） - ctxWithA := middleware.SetUserContext(ctx, accountA.ID, constants.UserTypePlatform, 100) - var resultsA []TestData - err := db.WithContext(ctxWithA). - Scopes(postgres.DataPermissionScope(ctxWithA, accountStore)). - Find(&resultsA).Error - require.NoError(t, err) - - // 降级策略应该只返回自己的数据 - assert.Len(t, resultsA, 1, "查询下级 ID 失败时，应该降级为只返回自己的数据") - assert.Equal(t, "data_a", resultsA[0].Name) -} diff --git a/tests/unit/model_test.go b/tests/unit/model_test.go deleted file mode 100644 index 56903db..0000000 --- a/tests/unit/model_test.go +++ /dev/null @@ -1,502 +0,0 @@ -package unit - -import ( - "testing" - "time" - - "github.com/break/junhong_cmp_fiber/internal/model" - "github.com/break/junhong_cmp_fiber/pkg/constants" - "github.com/go-playground/validator/v10" - "github.com/stretchr/testify/assert" -) - -// TestUserValidation 测试用户模型验证 -func TestUserValidation(t *testing.T) { - validate := validator.New() - - t.Run("有效的创建用户请求", func(t *testing.T) { - req := &model.CreateUserRequest{ - Username: "validuser", - Email: "valid@example.com", - Password: "password123", - } - - err := validate.Struct(req) - assert.NoError(t, err) - }) - - t.Run("用户名太短", func(t *testing.T) { - req := &model.CreateUserRequest{ - Username: "ab", // 少于 3 个字符 - Email: "valid@example.com", - Password: "password123", - } - - err := validate.Struct(req) - assert.Error(t, err) - }) - - t.Run("用户名太长", func(t *testing.T) { - req := &model.CreateUserRequest{ - Username: "a123456789012345678901234567890123456789012345678901", // 超过 50 个字符 - Email: "valid@example.com", - Password: "password123", - } - - err := validate.Struct(req) - assert.Error(t, err) - }) - - t.Run("无效的邮箱格式", func(t *testing.T) { - req := &model.CreateUserRequest{ - Username: "validuser", - Email: "invalid-email", - Password: "password123", - } - - err := validate.Struct(req) - assert.Error(t, err) - }) - - t.Run("密码太短", func(t *testing.T) { - req := &model.CreateUserRequest{ - Username: "validuser", - Email: "valid@example.com", - Password: "short", // 少于 8 个字符 - } - - err := validate.Struct(req) - assert.Error(t, err) - }) - - t.Run("缺少必填字段", func(t *testing.T) { - req := &model.CreateUserRequest{ - Username: "validuser", - // 缺少 Email 和 Password - } - - err := validate.Struct(req) - assert.Error(t, err) - }) -} - -// TestUserUpdateValidation 测试用户更新验证 -func TestUserUpdateValidation(t *testing.T) { - validate := validator.New() - - t.Run("有效的更新请求", func(t *testing.T) { - email := "newemail@example.com" - status := constants.UserStatusActive - req := &model.UpdateUserRequest{ - Email: &email, - Status: &status, - } - - err := validate.Struct(req) - assert.NoError(t, err) - }) - - t.Run("无效的邮箱格式", func(t *testing.T) { - email := "invalid-email" - req := &model.UpdateUserRequest{ - Email: &email, - } - - err := validate.Struct(req) - assert.Error(t, err) - }) - - t.Run("无效的状态值", func(t *testing.T) { - status := "invalid_status" - req := &model.UpdateUserRequest{ - Status: &status, - } - - err := validate.Struct(req) - assert.Error(t, err) - }) - - t.Run("空更新请求", func(t *testing.T) { - req := &model.UpdateUserRequest{} - - err := validate.Struct(req) - assert.NoError(t, err) // 空更新请求应该是有效的 - }) -} - -// TestOrderValidation 测试订单模型验证 -func TestOrderValidation(t *testing.T) { - validate := validator.New() - - t.Run("有效的创建订单请求", func(t *testing.T) { - req := &model.CreateOrderRequest{ - OrderID: "ORD-2025-001", - UserID: 1, - Amount: 10000, - Remark: "测试订单", - } - - err := validate.Struct(req) - assert.NoError(t, err) - }) - - t.Run("订单号太短", func(t *testing.T) { - req := &model.CreateOrderRequest{ - OrderID: "ORD-123", // 少于 10 个字符 - UserID: 1, - Amount: 10000, - } - - err := validate.Struct(req) - assert.Error(t, err) - }) - - t.Run("订单号太长", func(t *testing.T) { - req := &model.CreateOrderRequest{ - OrderID: "ORD-12345678901234567890123456789012345678901234567890", // 超过 50 个字符 - UserID: 1, - Amount: 10000, - } - - err := validate.Struct(req) - assert.Error(t, err) - }) - - t.Run("用户ID无效", func(t *testing.T) { - req := &model.CreateOrderRequest{ - OrderID: "ORD-2025-001", - UserID: 0, // 用户ID必须大于0 - Amount: 10000, - } - - err := validate.Struct(req) - assert.Error(t, err) - }) - - t.Run("金额为负数", func(t *testing.T) { - req := &model.CreateOrderRequest{ - OrderID: "ORD-2025-001", - UserID: 1, - Amount: -1000, // 金额不能为负数 - } - - err := validate.Struct(req) - assert.Error(t, err) - }) - - t.Run("缺少必填字段", func(t *testing.T) { - req := &model.CreateOrderRequest{ - OrderID: "ORD-2025-001", - // 缺少 UserID 和 Amount - } - - err := validate.Struct(req) - assert.Error(t, err) - }) -} - -// TestOrderUpdateValidation 测试订单更新验证 -func TestOrderUpdateValidation(t *testing.T) { - validate := validator.New() - - t.Run("有效的更新请求", func(t *testing.T) { - status := constants.OrderStatusPaid - remark := "已支付" - req := &model.UpdateOrderRequest{ - Status: &status, - Remark: &remark, - } - - err := validate.Struct(req) - assert.NoError(t, err) - }) - - t.Run("无效的状态值", func(t *testing.T) { - status := "invalid_status" - req := &model.UpdateOrderRequest{ - Status: &status, - } - - err := validate.Struct(req) - assert.Error(t, err) - }) -} - -// TestUserModel 测试用户模型 -func TestUserModel(t *testing.T) { - t.Run("创建用户模型", func(t *testing.T) { - user := &model.User{ - Username: "testuser", - Email: "test@example.com", - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - - assert.Equal(t, "testuser", user.Username) - assert.Equal(t, "test@example.com", user.Email) - assert.Equal(t, constants.UserStatusActive, user.Status) - }) - - t.Run("用户表名", func(t *testing.T) { - user := &model.User{} - assert.Equal(t, "tb_user", user.TableName()) - }) - - t.Run("软删除字段", func(t *testing.T) { - user := &model.User{ - Username: "testuser", - Email: "test@example.com", - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - - // DeletedAt 应该是 nil (未删除) - assert.True(t, user.DeletedAt.Time.IsZero()) - }) - - t.Run("LastLoginAt 可选字段", func(t *testing.T) { - user := &model.User{ - Username: "testuser", - Email: "test@example.com", - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - - assert.Nil(t, user.LastLoginAt) - - // 设置登录时间 - now := time.Now() - user.LastLoginAt = &now - assert.NotNil(t, user.LastLoginAt) - assert.Equal(t, now, *user.LastLoginAt) - }) -} - -// TestOrderModel 测试订单模型 -func TestOrderModel(t *testing.T) { - t.Run("创建订单模型", func(t *testing.T) { - order := &model.Order{ - OrderID: "ORD-2025-001", - UserID: 1, - Amount: 10000, - Status: constants.OrderStatusPending, - Remark: "测试订单", - } - - assert.Equal(t, "ORD-2025-001", order.OrderID) - assert.Equal(t, uint(1), order.UserID) - assert.Equal(t, int64(10000), order.Amount) - assert.Equal(t, constants.OrderStatusPending, order.Status) - }) - - t.Run("订单表名", func(t *testing.T) { - order := &model.Order{} - assert.Equal(t, "tb_order", order.TableName()) - }) - - t.Run("可选时间字段", func(t *testing.T) { - order := &model.Order{ - OrderID: "ORD-2025-001", - UserID: 1, - Amount: 10000, - Status: constants.OrderStatusPending, - } - - assert.Nil(t, order.PaidAt) - assert.Nil(t, order.CompletedAt) - - // 设置支付时间 - now := time.Now() - order.PaidAt = &now - assert.NotNil(t, order.PaidAt) - assert.Equal(t, now, *order.PaidAt) - }) -} - -// TestBaseModel 测试基础模型 -func TestBaseModel(t *testing.T) { - t.Run("BaseModel 字段", func(t *testing.T) { - user := &model.User{ - Username: "testuser", - Email: "test@example.com", - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - - // ID 应该是 0 (未保存) - assert.Zero(t, user.ID) - - // 时间戳应该是零值 - assert.True(t, user.CreatedAt.IsZero()) - assert.True(t, user.UpdatedAt.IsZero()) - }) -} - -// TestUserStatusConstants 测试用户状态常量 -func TestUserStatusConstants(t *testing.T) { - t.Run("用户状态常量定义", func(t *testing.T) { - assert.Equal(t, "active", constants.UserStatusActive) - assert.Equal(t, "inactive", constants.UserStatusInactive) - assert.Equal(t, "suspended", constants.UserStatusSuspended) - }) - - t.Run("用户状态验证", func(t *testing.T) { - validStatuses := []string{ - constants.UserStatusActive, - constants.UserStatusInactive, - constants.UserStatusSuspended, - } - - for _, status := range validStatuses { - user := &model.User{ - Username: "testuser", - Email: "test@example.com", - Password: "hashedpassword", - Status: status, - } - assert.Contains(t, validStatuses, user.Status) - } - }) -} - -// TestOrderStatusConstants 测试订单状态常量 -func TestOrderStatusConstants(t *testing.T) { - t.Run("订单状态常量定义", func(t *testing.T) { - assert.Equal(t, "pending", constants.OrderStatusPending) - assert.Equal(t, "paid", constants.OrderStatusPaid) - assert.Equal(t, "processing", constants.OrderStatusProcessing) - assert.Equal(t, "completed", constants.OrderStatusCompleted) - assert.Equal(t, "cancelled", constants.OrderStatusCancelled) - }) - - t.Run("订单状态流转", func(t *testing.T) { - order := &model.Order{ - OrderID: "ORD-2025-001", - UserID: 1, - Amount: 10000, - Status: constants.OrderStatusPending, - } - - // 订单状态流转：pending -> paid -> processing -> completed - assert.Equal(t, constants.OrderStatusPending, order.Status) - - order.Status = constants.OrderStatusPaid - assert.Equal(t, constants.OrderStatusPaid, order.Status) - - order.Status = constants.OrderStatusProcessing - assert.Equal(t, constants.OrderStatusProcessing, order.Status) - - order.Status = constants.OrderStatusCompleted - assert.Equal(t, constants.OrderStatusCompleted, order.Status) - }) - - t.Run("订单取消", func(t *testing.T) { - order := &model.Order{ - OrderID: "ORD-2025-002", - UserID: 1, - Amount: 10000, - Status: constants.OrderStatusPending, - } - - // 从任何状态都可以取消 - order.Status = constants.OrderStatusCancelled - assert.Equal(t, constants.OrderStatusCancelled, order.Status) - }) -} - -// TestUserResponse 测试用户响应模型 -func TestUserResponse(t *testing.T) { - t.Run("创建用户响应", func(t *testing.T) { - now := time.Now() - resp := &model.UserResponse{ - ID: 1, - Username: "testuser", - Email: "test@example.com", - Status: constants.UserStatusActive, - CreatedAt: now, - UpdatedAt: now, - } - - assert.Equal(t, uint(1), resp.ID) - assert.Equal(t, "testuser", resp.Username) - assert.Equal(t, "test@example.com", resp.Email) - assert.Equal(t, constants.UserStatusActive, resp.Status) - }) - - t.Run("用户响应不包含密码", func(t *testing.T) { - // UserResponse 结构体不应该包含 Password 字段 - resp := &model.UserResponse{ - ID: 1, - Username: "testuser", - Email: "test@example.com", - Status: constants.UserStatusActive, - } - - // 验证结构体大小合理 (不包含密码字段) - assert.NotNil(t, resp) - }) -} - -// TestListResponse 测试列表响应模型 -func TestListResponse(t *testing.T) { - t.Run("用户列表响应", func(t *testing.T) { - users := []model.UserResponse{ - {ID: 1, Username: "user1", Email: "user1@example.com", Status: constants.UserStatusActive}, - {ID: 2, Username: "user2", Email: "user2@example.com", Status: constants.UserStatusActive}, - } - - resp := &model.ListUsersResponse{ - Users: users, - Page: 1, - PageSize: 20, - Total: 100, - TotalPages: 5, - } - - assert.Equal(t, 2, len(resp.Users)) - assert.Equal(t, 1, resp.Page) - assert.Equal(t, 20, resp.PageSize) - assert.Equal(t, int64(100), resp.Total) - assert.Equal(t, 5, resp.TotalPages) - }) - - t.Run("订单列表响应", func(t *testing.T) { - orders := []model.OrderResponse{ - {ID: 1, OrderID: "ORD-001", UserID: 1, Amount: 10000, Status: constants.OrderStatusPending}, - {ID: 2, OrderID: "ORD-002", UserID: 1, Amount: 20000, Status: constants.OrderStatusPaid}, - } - - resp := &model.ListOrdersResponse{ - Orders: orders, - Page: 1, - PageSize: 20, - Total: 50, - TotalPages: 3, - } - - assert.Equal(t, 2, len(resp.Orders)) - assert.Equal(t, 1, resp.Page) - assert.Equal(t, 20, resp.PageSize) - assert.Equal(t, int64(50), resp.Total) - assert.Equal(t, 3, resp.TotalPages) - }) -} - -// TestFieldTags 测试字段标签 -func TestFieldTags(t *testing.T) { - t.Run("User GORM 标签", func(t *testing.T) { - user := &model.User{} - - // 验证 TableName 方法存在 - tableName := user.TableName() - assert.Equal(t, "tb_user", tableName) - }) - - t.Run("Order GORM 标签", func(t *testing.T) { - order := &model.Order{} - - // 验证 TableName 方法存在 - tableName := order.TableName() - assert.Equal(t, "tb_order", tableName) - }) -} diff --git a/tests/unit/store_test.go b/tests/unit/store_test.go deleted file mode 100644 index b5cf927..0000000 --- a/tests/unit/store_test.go +++ /dev/null @@ -1,550 +0,0 @@ -package unit - -import ( - "context" - "errors" - "testing" - "time" - - "github.com/break/junhong_cmp_fiber/internal/model" - "github.com/break/junhong_cmp_fiber/internal/store/postgres" - "github.com/break/junhong_cmp_fiber/pkg/constants" - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/require" - "go.uber.org/zap" - "gorm.io/driver/sqlite" - "gorm.io/gorm" - "gorm.io/gorm/logger" -) - -// setupTestStore 创建内存数据库用于单元测试 -func setupTestStore(t *testing.T) (*postgres.Store, func()) { - // 使用 SQLite 内存数据库进行单元测试 - db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{ - Logger: logger.Default.LogMode(logger.Silent), - }) - require.NoError(t, err, "创建内存数据库失败") - - // 自动迁移 - err = db.AutoMigrate(&model.User{}, &model.Order{}) - require.NoError(t, err, "数据库迁移失败") - - // 创建测试 logger - testLogger := zap.NewNop() - store := postgres.NewStore(db, testLogger) - - cleanup := func() { - sqlDB, _ := db.DB() - if sqlDB != nil { - sqlDB.Close() - } - } - - return store, cleanup -} - -// TestUserStore 测试用户 Store 层 -func TestUserStore(t *testing.T) { - store, cleanup := setupTestStore(t) - defer cleanup() - - ctx := context.Background() - - t.Run("创建用户成功", func(t *testing.T) { - user := &model.User{ - Username: "testuser", - Email: "test@example.com", - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - - err := store.User.Create(ctx, user) - assert.NoError(t, err) - assert.NotZero(t, user.ID) - assert.False(t, user.CreatedAt.IsZero()) - assert.False(t, user.UpdatedAt.IsZero()) - }) - - t.Run("创建重复用户名失败", func(t *testing.T) { - user1 := &model.User{ - Username: "duplicate", - Email: "user1@example.com", - Password: "password1", - Status: constants.UserStatusActive, - } - err := store.User.Create(ctx, user1) - require.NoError(t, err) - - // 尝试创建相同用户名 - user2 := &model.User{ - Username: "duplicate", - Email: "user2@example.com", - Password: "password2", - Status: constants.UserStatusActive, - } - err = store.User.Create(ctx, user2) - assert.Error(t, err, "应该返回唯一约束错误") - }) - - t.Run("根据ID查询用户", func(t *testing.T) { - user := &model.User{ - Username: "findbyid", - Email: "findbyid@example.com", - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - err := store.User.Create(ctx, user) - require.NoError(t, err) - - found, err := store.User.GetByID(ctx, user.ID) - assert.NoError(t, err) - assert.Equal(t, user.Username, found.Username) - assert.Equal(t, user.Email, found.Email) - }) - - t.Run("查询不存在的用户", func(t *testing.T) { - _, err := store.User.GetByID(ctx, 99999) - assert.Error(t, err) - assert.Equal(t, gorm.ErrRecordNotFound, err) - }) - - t.Run("根据用户名查询用户", func(t *testing.T) { - user := &model.User{ - Username: "findbyname", - Email: "findbyname@example.com", - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - err := store.User.Create(ctx, user) - require.NoError(t, err) - - found, err := store.User.GetByUsername(ctx, "findbyname") - assert.NoError(t, err) - assert.Equal(t, user.ID, found.ID) - }) - - t.Run("更新用户", func(t *testing.T) { - user := &model.User{ - Username: "updatetest", - Email: "update@example.com", - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - err := store.User.Create(ctx, user) - require.NoError(t, err) - - // 更新用户 - user.Email = "newemail@example.com" - user.Status = constants.UserStatusInactive - err = store.User.Update(ctx, user) - assert.NoError(t, err) - - // 验证更新 - found, err := store.User.GetByID(ctx, user.ID) - assert.NoError(t, err) - assert.Equal(t, "newemail@example.com", found.Email) - assert.Equal(t, constants.UserStatusInactive, found.Status) - }) - - t.Run("软删除用户", func(t *testing.T) { - user := &model.User{ - Username: "deletetest", - Email: "delete@example.com", - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - err := store.User.Create(ctx, user) - require.NoError(t, err) - - // 软删除 - err = store.User.Delete(ctx, user.ID) - assert.NoError(t, err) - - // 验证已删除 - _, err = store.User.GetByID(ctx, user.ID) - assert.Error(t, err) - assert.Equal(t, gorm.ErrRecordNotFound, err) - }) - - t.Run("分页列表查询", func(t *testing.T) { - // 创建10个用户 - for i := 1; i <= 10; i++ { - user := &model.User{ - Username: "listuser" + string(rune('0'+i)), - Email: "list" + string(rune('0'+i)) + "@example.com", - Password: "password", - Status: constants.UserStatusActive, - } - err := store.User.Create(ctx, user) - require.NoError(t, err) - } - - // 第一页 - users, total, err := store.User.List(ctx, 1, 5) - assert.NoError(t, err) - assert.GreaterOrEqual(t, len(users), 5) - assert.GreaterOrEqual(t, total, int64(10)) - - // 第二页 - users2, total2, err := store.User.List(ctx, 2, 5) - assert.NoError(t, err) - assert.GreaterOrEqual(t, len(users2), 5) - assert.Equal(t, total, total2) - - // 验证不同页的数据不同 - if len(users) > 0 && len(users2) > 0 { - assert.NotEqual(t, users[0].ID, users2[0].ID) - } - }) -} - -// TestOrderStore 测试订单 Store 层 -func TestOrderStore(t *testing.T) { - store, cleanup := setupTestStore(t) - defer cleanup() - - ctx := context.Background() - - // 创建测试用户 - user := &model.User{ - Username: "orderuser", - Email: "orderuser@example.com", - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - err := store.User.Create(ctx, user) - require.NoError(t, err) - - t.Run("创建订单成功", func(t *testing.T) { - order := &model.Order{ - OrderID: "ORD-TEST-001", - UserID: user.ID, - Amount: 10000, - Status: constants.OrderStatusPending, - Remark: "测试订单", - } - - err := store.Order.Create(ctx, order) - assert.NoError(t, err) - assert.NotZero(t, order.ID) - assert.False(t, order.CreatedAt.IsZero()) - }) - - t.Run("创建重复订单号失败", func(t *testing.T) { - order1 := &model.Order{ - OrderID: "ORD-DUP-001", - UserID: user.ID, - Amount: 10000, - Status: constants.OrderStatusPending, - } - err := store.Order.Create(ctx, order1) - require.NoError(t, err) - - // 尝试创建相同订单号 - order2 := &model.Order{ - OrderID: "ORD-DUP-001", - UserID: user.ID, - Amount: 20000, - Status: constants.OrderStatusPending, - } - err = store.Order.Create(ctx, order2) - assert.Error(t, err, "应该返回唯一约束错误") - }) - - t.Run("根据ID查询订单", func(t *testing.T) { - order := &model.Order{ - OrderID: "ORD-FIND-001", - UserID: user.ID, - Amount: 20000, - Status: constants.OrderStatusPending, - } - err := store.Order.Create(ctx, order) - require.NoError(t, err) - - found, err := store.Order.GetByID(ctx, order.ID) - assert.NoError(t, err) - assert.Equal(t, order.OrderID, found.OrderID) - assert.Equal(t, order.Amount, found.Amount) - }) - - t.Run("根据订单号查询", func(t *testing.T) { - order := &model.Order{ - OrderID: "ORD-FIND-002", - UserID: user.ID, - Amount: 30000, - Status: constants.OrderStatusPending, - } - err := store.Order.Create(ctx, order) - require.NoError(t, err) - - found, err := store.Order.GetByOrderID(ctx, "ORD-FIND-002") - assert.NoError(t, err) - assert.Equal(t, order.ID, found.ID) - }) - - t.Run("根据用户ID列表查询", func(t *testing.T) { - // 创建多个订单 - for i := 1; i <= 5; i++ { - order := &model.Order{ - OrderID: "ORD-LIST-" + string(rune('0'+i)), - UserID: user.ID, - Amount: int64(i * 10000), - Status: constants.OrderStatusPending, - } - err := store.Order.Create(ctx, order) - require.NoError(t, err) - } - - orders, total, err := store.Order.ListByUserID(ctx, user.ID, 1, 10) - assert.NoError(t, err) - assert.GreaterOrEqual(t, len(orders), 5) - assert.GreaterOrEqual(t, total, int64(5)) - }) - - t.Run("更新订单状态", func(t *testing.T) { - order := &model.Order{ - OrderID: "ORD-UPDATE-001", - UserID: user.ID, - Amount: 50000, - Status: constants.OrderStatusPending, - } - err := store.Order.Create(ctx, order) - require.NoError(t, err) - - // 更新状态 - now := time.Now() - order.Status = constants.OrderStatusPaid - order.PaidAt = &now - err = store.Order.Update(ctx, order) - assert.NoError(t, err) - - // 验证更新 - found, err := store.Order.GetByID(ctx, order.ID) - assert.NoError(t, err) - assert.Equal(t, constants.OrderStatusPaid, found.Status) - assert.NotNil(t, found.PaidAt) - }) - - t.Run("软删除订单", func(t *testing.T) { - order := &model.Order{ - OrderID: "ORD-DELETE-001", - UserID: user.ID, - Amount: 60000, - Status: constants.OrderStatusPending, - } - err := store.Order.Create(ctx, order) - require.NoError(t, err) - - // 软删除 - err = store.Order.Delete(ctx, order.ID) - assert.NoError(t, err) - - // 验证已删除 - _, err = store.Order.GetByID(ctx, order.ID) - assert.Error(t, err) - assert.Equal(t, gorm.ErrRecordNotFound, err) - }) -} - -// TestStoreTransaction 测试事务功能 -func TestStoreTransaction(t *testing.T) { - store, cleanup := setupTestStore(t) - defer cleanup() - - ctx := context.Background() - - t.Run("事务提交成功", func(t *testing.T) { - var userID uint - var orderID uint - - err := store.Transaction(ctx, func(tx *postgres.Store) error { - // 创建用户 - user := &model.User{ - Username: "txuser1", - Email: "txuser1@example.com", - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - if err := tx.User.Create(ctx, user); err != nil { - return err - } - userID = user.ID - - // 创建订单 - order := &model.Order{ - OrderID: "ORD-TX-001", - UserID: user.ID, - Amount: 10000, - Status: constants.OrderStatusPending, - } - if err := tx.Order.Create(ctx, order); err != nil { - return err - } - orderID = order.ID - - return nil - }) - - assert.NoError(t, err) - - // 验证用户和订单都已创建 - user, err := store.User.GetByID(ctx, userID) - assert.NoError(t, err) - assert.Equal(t, "txuser1", user.Username) - - order, err := store.Order.GetByID(ctx, orderID) - assert.NoError(t, err) - assert.Equal(t, "ORD-TX-001", order.OrderID) - }) - - t.Run("事务回滚", func(t *testing.T) { - var userID uint - - err := store.Transaction(ctx, func(tx *postgres.Store) error { - // 创建用户 - user := &model.User{ - Username: "rollbackuser", - Email: "rollback@example.com", - Password: "hashedpassword", - Status: constants.UserStatusActive, - } - if err := tx.User.Create(ctx, user); err != nil { - return err - } - userID = user.ID - - // 模拟错误，触发回滚 - return errors.New("模拟错误") - }) - - assert.Error(t, err) - assert.Equal(t, "模拟错误", err.Error()) - - // 验证用户未创建（已回滚） - _, err = store.User.GetByID(ctx, userID) - assert.Error(t, err) - assert.Equal(t, gorm.ErrRecordNotFound, err) - }) - - t.Run("嵌套事务回滚", func(t *testing.T) { - var user1ID, user2ID uint - - err := store.Transaction(ctx, func(tx1 *postgres.Store) error { - // 外层事务：创建第一个用户 - user1 := &model.User{ - Username: "nested1", - Email: "nested1@example.com", - Password: "password", - Status: constants.UserStatusActive, - } - if err := tx1.User.Create(ctx, user1); err != nil { - return err - } - user1ID = user1.ID - - // 内层事务：创建第二个用户并失败 - err := tx1.Transaction(ctx, func(tx2 *postgres.Store) error { - user2 := &model.User{ - Username: "nested2", - Email: "nested2@example.com", - Password: "password", - Status: constants.UserStatusActive, - } - if err := tx2.User.Create(ctx, user2); err != nil { - return err - } - user2ID = user2.ID - - // 内层事务失败 - return errors.New("内层事务失败") - }) - - // 内层事务失败导致外层事务也失败 - return err - }) - - assert.Error(t, err) - - // 验证两个用户都未创建 - _, err = store.User.GetByID(ctx, user1ID) - assert.Error(t, err) - - _, err = store.User.GetByID(ctx, user2ID) - assert.Error(t, err) - }) -} - -// TestConcurrentAccess 测试并发访问 -func TestConcurrentAccess(t *testing.T) { - store, cleanup := setupTestStore(t) - defer cleanup() - - ctx := context.Background() - - t.Run("并发创建用户", func(t *testing.T) { - concurrency := 20 - errChan := make(chan error, concurrency) - - for i := 0; i < concurrency; i++ { - go func(index int) { - user := &model.User{ - Username: "concurrent" + string(rune('A'+index)), - Email: "concurrent" + string(rune('A'+index)) + "@example.com", - Password: "password", - Status: constants.UserStatusActive, - } - errChan <- store.User.Create(ctx, user) - }(i) - } - - // 收集结果 - successCount := 0 - for i := 0; i < concurrency; i++ { - err := <-errChan - if err == nil { - successCount++ - } - } - - assert.Equal(t, concurrency, successCount, "所有并发创建应该成功") - }) - - t.Run("并发读写同一用户", func(t *testing.T) { - // 创建测试用户 - user := &model.User{ - Username: "rwuser", - Email: "rwuser@example.com", - Password: "password", - Status: constants.UserStatusActive, - } - err := store.User.Create(ctx, user) - require.NoError(t, err) - - concurrency := 10 - done := make(chan bool, concurrency*2) - - // 并发读 - for i := 0; i < concurrency; i++ { - go func() { - _, err := store.User.GetByID(ctx, user.ID) - assert.NoError(t, err) - done <- true - }() - } - - // 并发写 - for i := 0; i < concurrency; i++ { - go func(index int) { - user.Status = constants.UserStatusActive - err := store.User.Update(ctx, user) - assert.NoError(t, err) - done <- true - }(i) - } - - // 等待所有操作完成 - for i := 0; i < concurrency*2; i++ { - <-done - } - }) -}