通过协调专业技能、代理和命令形成无缝构建工作流，编排从设计到文档的完整API开发生命周期的元技能。
API 开发
功能概述
API 开发是一项面向实际任务的技能，主要用于通过协调设计、 执行、 测试和文档, 将 API 开发的整个生命周期调整为单一的工作流程。它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。
核心要点
- 使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。
- 该技能适合需要稳定复用相关能力的场景，可作为自动化工作流的一部分，也便于后续检查、调整和扩展。
- 从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。
使用与执行
实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。
结果检查与注意事项
执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。
API 开发
通过将设计、实现、测试和文档编写协调为统一工作流，统筹管理完整的 API 开发生命周期。
适用场景
- 从零开始构建全新 API
- 向现有 API 添加新端点
- 重构或重新设计 API
- 规划 API 版本管理与迁移策略
- 执行完整 API 开发周期（设计 → 构建 → 测试 → 文档化 → 部署）
编排流程
请严格按以下步骤顺序执行。每一步均会路由至对应技能或工具。
1. 设计 API
加载 api-design 技能，定义资源模型、URL 结构、HTTP 方法语义、错误格式及分页策略。
交付成果：资源列表、端点映射图、请求/响应 Schema、错误格式规范
2. 生成 OpenAPI 规范
基于设计产出机器可读的 OpenAPI 3.x 规范。以 api-design/assets/openapi-template.yaml 中的 OpenAPI 模板为起点。
交付成果：openapi.yaml，需包含全部端点、Schema、认证方案及示例
3. 脚手架端点
为每个端点生成路由文件、请求/响应类型定义及验证 Schema，并按资源分组组织路由。
交付成果：按资源划分的路由文件、类型定义、验证 Schema
4. 实现业务逻辑
在服务层编写业务逻辑，包含输入验证、授权检查、数据库查询及恰当的错误传播机制。保持控制器轻量化——业务逻辑应置于服务层。
交付成果：服务模块、仓储层、中间件（认证、限流、CORS）
5. 测试
在三个层级编写测试：
- 单元测试 —— 验证服务逻辑、输入校验及错误处理
- 集成测试 —— 使用真实数据库验证端点行为
- 契约测试 —— 校验响应结构是否符合 OpenAPI 规范
交付成果：覆盖正常路径、异常场景、边界条件及认证逻辑的完整测试套件
6. 文档化
生成面向开发者的可读 API 文档，含使用示例与 SDK 代码片段。确保每个端点均具备描述、参数说明、请求/响应示例及错误码说明。
交付成果：API 文档、变更日志、认证指南
7. 版本管理与部署
应用版本管理策略，打发布标签，更新变更日志，并通过流水线完成部署。参考 api-versioning 技能获取弃用与迁移指导。
交付成果：版本标签、变更日志条目、部署确认信息
API 设计决策表
根据实际用例选择合适的设计范式。
| 评估维度 | REST | GraphQL | gRPC |
|---|---|---|---|
| 适用场景 | 面向公众的 CRUD 密集型 API | 复杂关系型数据、客户端驱动的灵活查询 | 内部微服务通信、高吞吐量场景 |
| 数据获取方式 | 每个端点返回固定结构响应 | 客户端指定所需字段 | 强类型的 protobuf 消息 |
| 过度/不足获取问题 | 常见问题 | 设计上已解决 | 极小 —— Schema 显式定义 |
| 缓存支持 | 原生 HTTP 缓存（ETag、Cache-Control） | 需自定义缓存方案 | 无内置 HTTP 缓存机制 |
| 实时能力 | 轮询或 WebSocket | 内置订阅机制（Subscriptions） | 双向流式传输（Bidirectional streaming） |
| 工具生态 | 成熟 —— OpenAPI、Postman、curl | 持续演进 —— Apollo、Relay、GraphiQL | 成熟 —— protoc、grpcurl、Buf |
| 学习成本 | 低 | 中等 | 中高 |
| 版本管理 | URL 或请求头版本化 | 通过 @deprecated 进行 Schema 演化 |
.proto 文件中的包版本管理 |
经验法则：面向公众的 API 默认采用 REST；当客户端需跨关联数据进行灵活查询时选用 GraphQL；内部服务间通信优先选用 gRPC。
API 检查清单
在标记任意 API 工作为完成前，请逐项核对本清单。
认证与授权
- 已选定认证机制（JWT、OAuth2、API Key）
- 所有端点均已强制执行授权规则
- Token 已正确验证并作用域限定
- 敏感凭据安全存储（严禁硬编码于代码或日志中）
限流
- 已按端点或消费者等级配置限流策略
- 响应中已包含
RateLimit-*相关 HTTP 头 - 返回
429 Too Many Requests状态码，并附带Retry-After头 - 已面向调用方明确记录限流策略
分页
- 所有集合类端点均已启用分页
- 已选定分页方式（游标式或偏移式）
-
page_size已设定合理上限值 - 响应中已包含总数或
hasNextPage指示器
过滤与排序
- 过滤参数已校验并清洗
- 排序字段已白名单限制（禁止任意列排序）
- 已明确定义并记录默认排序规则
错误处理
- 所有端点均采用一致的错误响应 Schema
- 正确使用 HTTP 状态码（4xx 表示客户端错误，5xx 表示服务端错误）
- 校验失败时返回字段级详细错误信息
- 内部错误绝不泄露堆栈跟踪或敏感数据
版本管理
- 已选定并统一应用版本管理策略
- 已明确记录“破坏性变更”与“非破坏性变更”的判定标准
- 已通过
Sunset响应头向调用方传达弃用时间表
CORS
- 已配置允许的源（生产环境启用凭据时禁止使用通配符
*） - 已显式声明允许的 HTTP 方法与请求头
- 已正确处理预检（
OPTIONS）请求
文档
- OpenAPI / Swagger 规范已生成且保持最新
- 每个端点均包含描述、参数说明及示例响应
- 认证要求已明确记录
- 错误码及其含义已完整列出
- 每个版本均维护独立变更日志
安全
- 所有字段均执行输入校验
- 已防范 SQL 注入攻击
- 强制启用 HTTPS
- 敏感数据绝不出现在 URL 或日志中
- CORS 已正确配置
监控
- 已启用结构化日志并注入请求 ID
- 已配置错误追踪系统（如 Sentry、Datadog 等）
- 已采集性能指标（延迟、错误率）
- 已提供健康检查端点（
/health） - 已针对错误率突增配置告警
技能路由表
| 需求 | 技能 | 用途 |
|---|---|---|
| API 设计原则 | api-design |
资源建模、HTTP 语义、分页策略、错误格式规范 |
| 版本管理策略 | api-versioning |
版本生命周期管理、弃用机制、迁移模式 |
| 认证机制 | auth-patterns |
JWT、OAuth2、会话管理、RBAC、MFA |
| 错误处理 | error-handling |
错误分类、重试模式、熔断机制、HTTP 错误规范 |
| 限流 | rate-limiting |
限流算法、HTTP 响应头、分级限流、分布式限流 |
| 缓存 | caching |
缓存策略、HTTP 缓存机制、失效策略、Redis 使用模式 |
| 数据库迁移 | database-migrations |
Schema 演进、零停机部署、回滚策略 |
绝对禁止事项
- 绝对禁止跳过设计阶段 —— 直接编码将导致 API 不一致，后期修复成本极高
- 绝对禁止直接暴露数据库 Schema —— API 资源不等于数据库表；应围绕调用方使用场景进行设计
- 绝对禁止未配置认证即上线 —— 所有生产环境端点必须具备认证策略
- 绝对禁止返回不一致的错误格式 —— 所有错误响应必须遵循统一 Schema
- 绝对禁止在无版本管理计划下破坏已发布 API —— 破坏性变更必须引入新版本、配套迁移指南及明确弃用时间表
- 绝对禁止未经测试与文档化即部署 —— 未经测试的 API 必然引入缺陷，缺乏文档的 API 将严重挫伤开发者体验
相关专题
Vite项目打包部署专题汇集生产构建、产物预览、输出目录、资源路径、Nginx与GitHub Pages部署及常见白屏和路由404问题的已审核文章，帮助读者完成上线流程。
2026.10.28
0
16
Vite搭配Vue.js专题汇集创建Vue 3项目、配置开发环境、路径别名、Vue插件、代理、多环境构建与调试的已审核文章，帮助读者完成从初始化到日常开发的配置。
2026.10.28
0
15
Vite项目目录专题汇集入口文件、src源码、public静态资源、路径别名、项目根目录和构建输出目录相关的已审核文章，帮助读者理解各文件夹的用途与引用方式。
2026.10.28
0
10
本专题介绍Gradle插件开发的基本流程，涵盖插件类编写、自定义任务注册、扩展参数设计和插件应用方法，帮助你理解插件如何组织构建逻辑，减少多个项目之间的重复配置。
2026.10.22
0
11
本专题介绍Gradle Wrapper的基本作用，涵盖文件组成、生成方法、版本配置和任务调用，帮助你理解项目如何使用指定的Gradle版本，减少不同开发环境带来的构建差异。
2026.10.22
0
10
本专题整理Golangci-lint常用Linters的用途与配置方法，覆盖错误处理、无效代码、安全、复杂度、命名和依赖检查，帮助项目合理选规则。
2026.10.22
0
15
本专题介绍Gradle Java项目构建方法，涵盖Java插件配置、依赖声明、源码编译、测试执行和打包检查，帮助你理解各阶段的任务关系，逐步完成项目构建。
2026.10.22
0
10
本专题汇总PHP常见时间戳漏洞，包括2038年溢出、时区漂移、时间戳伪造、重放攻击、时间盲注与日志审计失效等，并给出升级64位环境、使用 DateTimeImmutable、统一UTC、严格超时校验、预处理绑定、hash_equals 比对等修复方案，帮助开发者快速排查和加固时间相关代码。
2026.10.22
0
25
本专题聚焦Golangci-lint YAML配置文件，讲清运行参数、规则启停、目录排除、问题过滤及严重级别设置，便于团队统一检查标准。
2026.10.22
0
15
热门下载
相关下载
精品课程
共6课时 | 54.7万人学习
共89课时 | 134.1万人学习
共49课时 | 82.5万人学习
