pma-go

Go 项目实现指南

将此技能与 /pma 配合使用。/pma 负责工作流、审批和任务跟踪；本指南定义审批后的实现基线。

保持此入口文件精简。仅加载任务所需的参考资料包。

适用范围

适用于由 PMA 管理的 Go 后端、API 服务和 CLI 应用。

不适用于嵌入式目标、没有二进制文件的纯库模块或非 PMA 项目。

加载顺序

1. 始终先加载 references/baseline.md。
2. 配置分层、验证、sqlc、pgx、GORM 和迁移相关任务，加载 references/config-and-data.md。
3. 处理处理程序、中间件、日志记录、可观测性和关停相关任务，加载 references/http-and-runtime.md。
4. 处理 lint、测试、任务运行器、安全审查、CI 和 Git 工作流相关任务，加载 references/delivery.md。

快速路由

• 新建服务或 CLI 设置 → references/baseline.md
• 配置（koanf 分层、环境变量映射、验证）→ references/config-and-data.md
• 数据访问（sqlc + pgx、GORM、迁移、仓储边界）→ references/config-and-data.md
• 运行时（HTTP 服务、中间件、slog、追踪、关停）→ references/http-and-runtime.md
• 开发 URL 路由（nsl）→ references/http-and-runtime.md（完整协议 → /pma references/dev-environment.md）
• 测试 → references/delivery.md
• CI 和交付（质量门禁、lint、Taskfile、安全检查清单、PR 就绪情况）→ references/delivery.md

参考资料包

• references/baseline.md 技术栈默认配置、质量门禁、目录布局、约定、错误模型和代码质量标准。
• references/config-and-data.md 使用 koanf 进行配置分层、验证、sqlc 搭配 pgx、GORM 替代方案和迁移规则。
• references/http-and-runtime.md 路由器结构、处理程序模式、中间件、日志记录、可观测性和优雅关停。
• references/delivery.md lint 配置、测试、任务运行器要求、安全检查、CI 和 Git 约定。

验收清单

合并前：

• goimports -l . 无输出；golangci-lint run 和 go vet ./... 均通过
• go test -cover ./... 通过；覆盖率目标为 80% 或更高
• go build ./... 成功；go mod tidy 不产生差异
• 修改的代码通过 gosec ./...
• 配置通过 koanf 分层（默认值 -> 文件 -> 环境变量 -> 标志）并在加载后完成验证
• 已接入优雅关停（signal.NotifyContext + 带超时的 http.Server.Shutdown）
• 服务附带 UI 时，nsl 开发路由正常工作（参见 references/http-and-runtime.md）

如果仓库现有做法与这些默认设置不一致，应明确说明差异，并在代码、文档和 CI 中保持一致。