api-development_开发编程 skill-PHP中文网

api-development

Polar Sponsor

爱发电赞助

.NET 9.0

立即下载

通过协调专业技能、代理和命令形成无缝构建工作流，编排从设计到文档的完整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 演进、零停机部署、回滚策略