build-api

后端 API 开发工作流

按照 NestJS 模式、Prisma schema 设计和项目的整洁架构规范，构建后端 API 端点、服务和数据库变更。

注意

范围边界：此技能负责实现后端代码并提交代码。它不会创建拉取请求、推送到远程仓库、运行代码审查，也不会提交任何内容以供合并。实现和提交完成后，立即停止，并建议用户接下来运行 /review-code。

第 1 步：定义 API 需求

确保我们位于基于最新 main 的功能分支上。始终先获取更新：

git fetch origin main

如果当前位于 main，请从最新的 origin/main 创建新的功能分支：

git checkout -b feature/<feature-slug> origin/main

如果当前已位于现有功能分支，请将其变基到最新的 origin/main，以获取所有变更：

git status --porcelain

如果工作树有未提交的变更，请在变基前暂存这些变更：

git stash push -m "build-api: stash before rebase"
git rebase origin/main
git stash pop

如果工作树干净，请直接变基：

git rebase origin/main

如果用户提供了 GitHub issue 编号（例如，/build-api 42 或 /build-api #42），请获取该 issue 并标记工作正在进行中（规则请参阅 AGENTS.md 中的“标签管理”）：

gh issue view <number> --json title,body,labels,state,number

# Single-developer constraint: only one issue should be in-progress at a time.
# First, remove in-progress from any other issue that has it:
gh issue list --label "in-progress" --state open --json number --jq '.[].number' | while read n; do
  gh issue edit "$n" --remove-label "in-progress"
done

gh issue edit <number> --add-label "in-progress"

确认该 issue 已在 产品路线图项目看板中跟踪。如果没有，请将其添加到看板：

# --limit 200 covers the current board size; increase if the project grows beyond 200 items
EXISTING=$(gh project item-list {PROJECT_NUMBER} --owner {OWNER} --format json --limit 200 \
  | python3 -c "
import json, sys
data = json.load(sys.stdin)
for item in data.get('items', []):
    # <number> must be an integer literal, e.g., == 42, not == '42'
    if item.get('content', {}).get('number') == <number>:
        print(item['id'])
        break
")

if [ -z "$EXISTING" ]; then
  ITEM_ID=$(gh project item-add {PROJECT_NUMBER} --owner {OWNER} --url "https://github.com/{OWNER}/{REPO}/issues/<number>" --format json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")
  echo "Warning: Issue #<number> was not on the project board. Added it now (item $ITEM_ID)."
fi

警告

如果 issue 不在项目看板中，它的阶段、规模和日期字段也可能未填写。检查项目条目，如果字段未设置，请提醒用户——这表明该 issue 可能是在 /plan-feature 或 /security-audit 之外创建的，而这两个技能会确保 issue 加入看板并填写相关字段。

询问用户（如果已先运行 /plan-feature，则从决策记录或 issue 正文中读取）：

• 要创建或修改哪些资源和端点？
• 需要哪些操作（CRUD、自定义操作、查询）？
• 是否需要变更数据库 schema？
• 这是 tRPC 程序还是 REST 端点？
• 是否有身份验证或授权要求？

如果 docs/decisions/ 中存在决策记录，请阅读其中的任务拆解。

第 2 步：设计 API 契约

调用 /backend-development:api-design-principles，获取 API 设计指导。

设计完整的 API 契约：

• 端点路径和 HTTP 方法（REST）或程序名称（tRPC）
• 请求类型：包含所有字段及可选/必填标记的完整 TypeScript 接口
• 响应类型：成功响应、错误响应，以及适用时的分页信息
• 验证规则：使用 Zod schema 进行运行时验证
• 错误格式：标准化的错误响应结构
• 身份验证要求：哪些端点需要身份验证、基于角色的访问控制

如果这涉及重大 API 决策（新的资源类型、对现有 API 的破坏性变更、新的架构模式），请使用 .claude/councils/architecture-council.md 启动架构委员会：

模型选择：有关 Agent 模型规格与 Task 工具参数的映射，请参阅 README.md 中的模型选择部分。

首席工程师 — 咨询：full-stack-orchestration

• 投票：批准 / 有疑虑 / 否决
• 理由：架构合理性、可扩展性、可维护性
• 建议：应遵循的模式、需要考虑的权衡

平台工程师 — 咨询：cloud-infrastructure

• 投票：批准 / 有疑虑 / 否决
• 理由：运维影响、部署注意事项
• 建议：基础设施方面的考虑、监控需求

安全工程师 — 咨询：security-scanning

• 投票：批准 / 有疑虑 / 否决
• 理由：安全风险、攻击面、合规性
• 建议：安全加固步骤、输入验证

后端专家 — 咨询：backend-development

• 投票：批准 / 有疑虑 / 否决
• 理由：API 设计质量、NestJS 模式、开发者体验
• 建议：实现方法、生态系统集成

检查点：向用户展示 API 契约（以及已启用时的架构委员会评估）。等待用户批准后再开始实现。

第 3 步：数据库层（如有需要）

如果需要更改架构：

1. 调用 /database-design:postgresql 获取 PostgreSQL 架构设计指导

2. 设计 Prisma 架构变更：

   • 使用恰当字段类型定义模型
   • 定义关系和外键
   • 为查询性能添加索引
   • 添加唯一约束和验证
   • 适当使用枚举

3. 调用 /database-migrations:sql-migrations 获取迁移生成指导

检查点：向用户展示 Prisma 架构变更和迁移计划。等待用户批准后再运行迁移。

4. 生成并应用迁移：

   pnpm db:migrate
   

5. 如需种子数据，请更新种子脚本。

第 4 步：实现后端

遵循 NestJS 模式和 /backend-development:architecture-patterns，采用整洁架构：

类型和 DTO

• 定义请求／响应 TypeScript 接口
• 创建用于运行时验证的 Zod 验证架构
• 导出供前端使用的类型（通过 tRPC 或共享包）

仓库／数据访问层

• 创建或更新 Prisma 查询
• 实现数据访问模式（如使用，则采用仓库模式）
• 添加查询优化（选择特定字段，谨慎使用 includes）

服务层

• 在 NestJS 服务中实现业务逻辑
• 添加输入验证和业务规则校验
• 使用带类型的异常处理错误情况
• 确保服务可测试（注入依赖）

控制器／路由层

• 创建 tRPC 过程或 NestJS 控制器
• 接入验证、身份验证守卫和服务
• 实现适当的 HTTP 状态码（REST）或错误码（tRPC）
• 如公共端点有需要，添加速率限制

守卫和中间件

• 在需要时添加身份验证守卫
• 添加授权检查（基于角色或资源）
• 添加请求日志以便调试

对于复杂类型场景（泛型、条件类型、映射类型），使用 /javascript-typescript:typescript-advanced-types。

对于性能敏感的端点，调用 /application-performance:performance-optimization 获取 API 性能分析和优化模式。

第 5 步：编写测试

遵循 QA 负责人制定的测试策略：

单元测试

• 单独测试每个服务方法
• 模拟 Prisma 客户端和外部依赖
• 测试业务逻辑、验证规则和错误处理
• 覆盖正常路径和边缘情况

集成测试

• 针对真实（测试）数据库测试端点
• 验证请求验证会拒绝无效输入
• 验证身份验证和授权是否生效
• 测试各种失败场景下的错误响应

验证测试

• 边界条件（空字符串、最大长度、特殊字符）
• 无效输入格式
• 缺少必填字段
• 类型强制转换和类型转换

运行测试并验证覆盖率：

pnpm test

确保覆盖率达到 >80% 的目标。

第 6 步：生成 API 文档

调用 /documentation-generation:openapi-spec-generation，为新端点生成或更新 API 文档。

如果使用 tRPC，请记录过程签名和用法示例。 如果使用 REST，请生成或更新 OpenAPI／Swagger 规范。

第 7 步：自我审查

向用户展示之前，请确认：

pnpm type-check      # No TypeScript errors
pnpm lint            # No linting violations
pnpm format:check    # No Prettier formatting issues
pnpm test            # All unit tests pass
pnpm test:smoke      # DI container and HTTP pipeline boot OK

如果 format:check 失败，请对报告的文件运行 pnpm exec prettier --write，再继续。

检查常见问题：

• 没有硬编码的机密或凭据
• 正确处理错误（不吞掉错误）
• 所有面向外部的端点都进行了输入验证
• 正确使用 TypeScript 严格模式（不使用 any 类型）

步骤 8：更新文档

如果此 API 变更改变了项目的设置、构建或运行方式，请在提交之前更新相关文档：

1. README.md — 如果变更引入了新的基础设施、服务、环境变量或命令，请更新 Quick Start、Running the Application 或 Project Structure 部分
2. docs/DEVELOPMENT.md — 根据需要更新 Prerequisites、Local Development Setup、Database Operations 或 Troubleshooting 部分
3. Makefile — 为常见操作添加新的目标（例如，新的 Docker 服务、数据库命令）
4. .env.example 文件 — 添加新的环境变量，并提供清晰的说明和安全的默认值
5. docs/INDEX.md — 如果向 docs/ 添加了任何新文件，请将其添加到主文档索引中的相应表格

重要

刚克隆仓库的开发者必须仅按照 README.md 就能让项目运行。如果你的 API 变更添加了 Docker 服务、数据库、新的环境变量或外部依赖，文档必须反映这些变更。

步骤 9：提交

检查点：汇总所有变更，包括修改的文件、实现的 API 契约、测试结果和文档。等待用户批准。

使用 Conventional Commits 格式提交：

feat(api): add <resource> endpoints

或者，如果修改现有端点：

feat(api): update <resource> with <change-description>

更新 GitHub Issue

如果实现工作是从 GitHub Issue 发起的：

1. 在 Issue 中评论进度：

   gh issue comment <number> --body "Implementation committed on branch \`<branch-name>\`. Proceeding to code review via \`/review-code\`."
   

说明

此处不要移除 in-progress 标签。此标签会一直保留在 Issue 上，直到 Issue 关闭（由 .github/workflows/label-cleanup.yml 自动处理）。这样可以确保在代码审查和提交 PR 期间，Issue 始终明显处于进行中状态。

步骤 10：交接 — 在此停止

注意

此技能的工作已完成。 不要继续创建拉取请求、推送到远程仓库或执行代码审查。这些是独立的技能，有各自的工作流和检查点。

向用户说明下一步：

• 建议：提交前运行 /review-code，进行多角度的安全性和质量审查
• 如果还有工作未完成：继续完成剩余任务，然后运行 /review-code

如果工作来自 GitHub Issue，请提醒用户：

• PR 应通过 Closes #<number> 引用该 Issue，以便在合并时自动关闭
• /submit-pr 会从提交消息中检测相关 Issue

流程：/plan-feature → /build-feature 或 /build-api → /review-code → /submit-pr

不要从此技能中推送分支、创建 PR 或调用 /submit-pr。