chore: track .codebuddy project metadata

2026-10-25 20:30:23 +08:00
parent 332b7dcd08
commit e1f03a3033
3 changed files with 447 additions and 3 deletions
@@ -0,0 +1,104 @@
+---
+description: Go 后端项目 portal-mini-go 的核心开发规范，涵盖错误处理、目录结构、API 约定、Context、并发、测试与命名等需要人工/AI 遵守的约定。适用于本项目所有 .go 代码。
+globs: "**/*.go"
+alwaysApply: true
+---
+
+# portal-mini-go 后端开发规范
+
+你是一名高级 Go 后端工程师。在编写、修改或审查本项目（portal-mini-go）的 Go 代码时，必须遵循以下规范。机器可自动处理的（gofmt/goimports/go vet）交由 lint 工具，以下约定需主动遵守。
+
+## 0. 项目定位
+- portal-mini-go 是基于 Go 的中后台/门户类后端服务。
+- 语言版本：Go 1.22+。module 名：`portal-mini-go`。
+- 未在本规则中明确约定的，遵循 [Effective Go](https://go.dev/doc/effective_go) 与 Google Go Style Guide。
+
+## 1. 推荐技术栈（默认；若本项目实际采用不同框架，修改本规则对应条目并保持一致）
+- Web 框架：gin
+- 参数校验：go-playground/validator/v10（`binding` tag）
+- 配置：viper + YAML，支持环境变量覆盖
+- 日志：`log/slog`（结构化；生产 JSON、本地 text）
+- 数据库：GORM（MySQL / PostgreSQL）
+- 缓存：go-redis/redis
+- 测试：`testing` + `testify`；mock 用 `gomock` 或 testify mock
+- 错误包装：`fmt.Errorf("...: %w", err)`
+
+## 2. 目录结构（强制）
+```
+cmd/            # 各可执行程序入口（main 包）
+internal/       # 私有业务代码，禁止被外部模块 import
+  handler/      # HTTP 接入层
+  service/      # 业务逻辑
+  repository/   # 数据访问（DB/Redis）
+  model/        # 领域模型/实体
+  pkg/          # 内部可复用工具（非对外公开）
+pkg/            # 对外公开、可安全被外部引用的公共库
+configs/        # 配置文件模板
+scripts/        # 构建/部署脚本
+```
+- 业务代码放 `internal/`，对外公开库放 `pkg/`。
+- 依赖方向：`handler → service → repository → model`，禁止反向依赖与循环依赖。
+- 禁止在 handler 中直接写 SQL 或调用 DB，必须经 service / repository 层。
+
+## 3. 错误处理（重点，必须）
+- 永远不要忽略 error；`_ = f()` 必须加注释说明为何可忽略，否则必须处理。
+- 向上传播错误使用 `fmt.Errorf("上下文: %w", err)` 保留错误链路。
+- 本层能合理处理才处理，否则向上返回；最终在 handler 层统一转换为 HTTP 状态码/响应。
+- 禁止用 `panic` 控制业务流程；`recover` 仅允许用于 goroutine 顶层与框架中间件。
+- 业务错误用哨兵变量或实现 `error` 接口的类型，并携带可被前端消费的错误码（如 `var ErrNotFound = errors.New("not found")`）。
+
+## 4. 命名与风格
+- 遵循 Go 惯例：导出标识符用驼峰；缩略语全大写（`ID`、`URL`、`HTTP`、`API`）。
+- 文件名小写下划线：`user_handler.go`。
+- 方法接收者用类型缩写（`u *User`），禁止 `this` / `self`。
+- 接口优先做小接口（单方法，常以 `-er` 结尾，如 `Reader`、`Closer`）。
+- 错误变量用 `Err` 前缀；包级常量用 `const` 块，避免裸魔法数字。
+
+## 5. 日志
+- 统一使用 `log/slog`，禁止 `fmt.Println` / `log.Print` 记录业务日志。
+- 关键路径记录 trace_id（从 context 取）、处理耗时、参数摘要；**禁止打印敏感信息与超大对象**。
+- 级别：debug（开发）、info（正常）、warn（可恢复异常）、error（需告警）。
+- 记录错误时必须带原始 error：`slog.Any("err", err)`。
+
+## 6. Context 与超时
+- 所有跨进程调用（HTTP / DB / Redis / RPC）必须把 `context.Context` 作为**第一个参数**接收并向下透传。
+- 不在 struct 字段中存储 context；用 `context.WithTimeout` / `WithDeadline` 设置超时。
+- 长生命周期场景禁止用 `time.After`（会泄漏），改用 `time.NewTimer` 并显式 `Stop`。
+
+## 7. 并发
+- 共享状态必须用 `sync.Mutex` / `atomic` / channel 同步，明确数据归属。
+- 每个 `go` 语句必须有明确的生命周期与退出条件；主 goroutine 退出前用 `sync.WaitGroup` 或 `errgroup` 等待。
+- 禁止无限制启动 goroutine；批量任务用受限 worker / 带缓冲 channel。
+- 一组相关 goroutine 优先用 `golang.org/x/sync/errgroup` 管理错误与取消。
+
+## 8. HTTP / API
+- RESTful 风格；统一响应结构：
+  ```go
+  type Response struct {
+      Code int         `json:"code"`
+      Msg  string      `json:"msg"`
+      Data interface{} `json:"data,omitempty"`
+  }
+  ```
+- 用统一中间件将 error 转换为响应，handler 内不直接散落 `c.JSON(http.StatusXxx, ...)` 处理错误。
+- 入参用 struct + validator 校验（`binding:"required"` 等），禁止信任未校验的客户端输入。
+- 所有 DB 查询使用参数化（GORM 占位符 / 预编译），禁止字符串拼接 SQL，杜绝注入。
+
+## 9. 测试
+- 核心 service / repository 必须写**表驱动测试**。
+- 断言用 `testify/require`（失败即停）或 `assert`；测试文件 `_test.go` 与被测同包或 `_test` 包。
+- 外部依赖（DB / Redis / 下游服务）用接口 + mock 隔离，不在单测中依赖真实中间件。
+- 提交前保证 `go test ./...` 通过；核心业务逻辑覆盖率目标 ≥ 60%。
+
+## 10. 配置与密钥
+- 密钥、连接串、token 绝不硬编码或提交仓库；从环境变量 / 密钥管理服务读取。
+- 配置优先级：默认值 < 配置文件 < 环境变量 < 命令行参数。
+- 本地 `.env` 必须加入 `.gitignore`。
+
+## 11. 提交与协作
+- 提交信息遵循 Conventional Commits（`feat` / `fix` / `refactor` / `chore` / `docs` / `test`）。
+- 每次变更须通过 `go vet`、`golangci-lint run`、`go test ./...` 后再提交。
+- 不向主干（如 `main`）直接 push；重大改动走 PR / 评审。
+
+---
+> 当本规则与具体实现的第三方库文档冲突时，以库文档为准；若确定采用不同于"推荐技术栈"的框架，请同步修改本规则第 1 条，保持规则与代码一致。