api-design

API 设计

涵盖 REST/GraphQL 框架设计、版本控制策略和 RFC 9457 错误处理的完整 API 设计模式。每个类别都有单独的规则文件，按需从 rules/ 加载。

快速参考

类别	规则	影响	适用场景
API 框架	3	HIGH	REST 约定、资源建模、OpenAPI 规范
版本控制	2	HIGH	URL 路径版本控制、标头版本控制；弃用期限是 references/ork-delta.md 中的内部政策
错误处理	1	HIGH	面向 Agent 的 RFC 9457 扩展；基础规范和 FastAPI 接线方式属于上游内容
GraphQL	2	HIGH	Strawberry 代码优先、DataLoader、权限、订阅
gRPC	2	HIGH	Protobuf 服务、流式传输、拦截器、重试
流式传输	2	HIGH	SSE 端点、WebSocket 双向通信、异步生成器
集成	2	HIGH	消息平台（WhatsApp、Telegram）、Payload CMS 模式

总计：7 个类别中的 14 条规则。 从精简文件中保留下来的内部决策见 references/ork-delta.md；供应商和规范材料采用链接形式，不再赘述（参见上游内容范围（勿重复））。

API 框架

用于打造一致、便于开发者使用的 API 的 REST 和 GraphQL 设计约定。

规则	文件	关键模式
REST 约定	rules/framework-rest-conventions.md	复数名词、HTTP 方法、状态码、分页
资源建模	rules/framework-resource-modeling.md	层级 URL、筛选、排序、字段选择
OpenAPI	rules/framework-openapi.md	OpenAPI 3.1 规范、文档、架构定义

版本控制

在不破坏客户端兼容性的前提下演进 API 的策略。

规则	文件	关键模式
URL 路径	rules/versioning-url-path.md	/api/v1/ 前缀路由、特定版本的架构
标头	rules/versioning-header.md	X-API-Version 标头、内容协商

弃用和日落：内部期限（提前 3 个月通知、6 个月后日落、支持当前版本及前一个版本）见 references/ork-delta.md；标头机制属于上游内容（RFC 8594、RFC 9745）。

错误处理

通过 RFC 9457 Problem Details 实现机器可读的标准化错误响应。

规则	文件	关键模式
面向 Agent 的错误	rules/errors-agent-facing.md	Agent 扩展：retryable、error_category、内容协商、令牌效率

RFC 9457 基础格式、FastAPI 异常处理器接线方式以及 Pydantic 422 映射属于上游内容（参见上游内容范围（勿重复））。这里保留的内部内容包括问题类型 URI 约定和类型化异常词汇表（见 references/ork-delta.md），完整的可运行实现见 examples/fastapi-problem-details.md。

GraphQL

采用代码优先方式设计 Strawberry GraphQL 架构，包含类型安全的解析器和 FastAPI 集成。

规则	文件	关键模式
架构设计	rules/graphql-strawberry.md	类型安全架构、DataLoader、联合错误、Private 字段
模式与身份验证	rules/graphql-schema.md	权限类、FastAPI 集成、订阅

gRPC

用于内部微服务通信的高性能 gRPC。

规则	文件	关键模式
服务定义	rules/grpc-service.md	Protobuf、异步服务端、客户端超时、代码生成
流式传输与拦截器	rules/grpc-streaming.md	服务端/双向流式传输、身份验证、重试退避

流式传输

通过 SSE、WebSockets 实现实时数据流传输，并妥善清理资源。

规则	文件	关键模式
SSE	rules/streaming-sse.md	SSE 端点、大模型流式传输、重新连接、保活
WebSocket	rules/streaming-websocket.md	双向通信、心跳、aclosing()、背压

集成

消息平台集成与无头 CMS 模式。

规则	文件	关键模式
消息平台	rules/messaging-integrations.md	WhatsApp WAHA、Telegram Bot API、Webhook 安全
Payload CMS	rules/payload-cms.md	Payload 3.0 集合、访问控制、CMS 选择

快速入门示例

# REST endpoint with versioning and RFC 9457 errors
from fastapi import APIRouter, Depends, Request
from fastapi.responses import JSONResponse

router = APIRouter()

@router.get("/api/v1/users/{user_id}")
async def get_user(user_id: str, service: UserService = Depends()):
    user = await service.get_user(user_id)
    if not user:
        raise NotFoundProblem(
            resource="User",
            resource_id=user_id,
        )
    return UserResponseV1(id=user.id, name=user.full_name)

关键决策

决策	建议
版本策略	面向公开 API 使用 URL 路径（/api/v1/）
资源命名	使用复数名词和 kebab-case
分页	大型数据集使用基于游标的分页
错误格式	使用 RFC 9457 Problem Details 和 application/problem+json
错误类型 URI	使用你的 API 域名，并添加 /problems/ 前缀
支持窗口	当前版本及之前 1 个版本
弃用通知	日落前至少 3 个月
日落期限	弃用后 6 个月
GraphQL 架构	使用 Strawberry 类型，以代码优先方式定义
防止 N+1	为所有嵌套解析器使用 DataLoader
GraphQL 身份验证	使用权限类（基于上下文）
gRPC proto	每个文件定义一个服务，共用 common.proto
gRPC 流式传输	列表使用服务端流式传输，实时场景使用双向流式传输
SSE 保活	每隔 30 秒
WebSocket 心跳	每隔 30 秒进行 ping-pong
异步生成器清理	对所有外部资源使用 aclosing()

常见错误

1. 在 URL 中使用动词（POST /createUser，而不是 POST /users）
2. 各端点的错误格式不一致
3. 未提升版本号就破坏契约
4. 使用纯文本错误响应，而不是 Problem Details
5. 弃用版本时未添加弃用标头
6. 在错误中暴露内部细节（堆栈跟踪、数据库错误）
7. 错误响应缺少 Content-Type: application/problem+json
8. 同时支持过多 API 版本（最多 2–3 个）
9. 缓存时未考虑版本隔离

上游覆盖内容（不要重述）

在 2026-07-31 的 wrap-plus-delta 精简中移除的主题。请查阅一手资料；只有 ork 增量内容（内部策略、经验教训、工作配置）属于此技能。

主题	一手资料
RFC 9457 Problem Details 规范（成员、媒体类型、about:blank、客户端解析）	https://www.rfc-editor.org/rfc/rfc9457.html
FastAPI 异常处理器、Pydantic 验证错误（422）、错误目录样板	https://fastapi.tiangolo.com/tutorial/handling-errors/
API 版本策略教程和 FastAPI 版本化路由器指南	https://fastapi.tiangolo.com/tutorial/bigger-applications/
Deprecation 和 Sunset 标头机制	https://www.rfc-editor.org/rfc/rfc8594.html and https://www.rfc-editor.org/rfc/rfc9745.html
通用 REST 参考（方法、状态码、分页形式、身份验证标头）	https://www.rfc-editor.org/rfc/rfc9110.html and https://developer.mozilla.org/en-US/docs/Web/HTTP
OpenAPI 3.1 规范编写（模板保留在 assets/openapi-template.yaml 中）	https://spec.openapis.org/oas/v3.1.0
gRPC proto 风格、服务定义、状态码	https://grpc.io/docs/ and https://protobuf.dev/programming-guides/style/
Payload CMS 集合设计、字段类型、访问控制	https://payloadcms.com/docs
前端 API 调用（Zod 边界验证、ky、TanStack Query）	https://zod.dev and https://tanstack.com/query/latest/docs
API 设计／错误处理／版本管理审查清单	可从上述规范推导；未保留清单重述

评测

请参阅 test-cases.json，其中包含涵盖所有类别的 13 个测试用例。

相关技能

• fastapi-advanced - FastAPI 专属实现模式
• rate-limiting - 高级速率限制实现和算法
• observability-monitoring - 版本使用指标和错误跟踪
• input-validation - API 错误处理之外的验证模式
• streaming-api-patterns - 实时 API 的 SSE 和 WebSocket 模式

能力详情

rest-design

关键词： rest、restful、http、endpoint、route、path、resource、CRUD 解决的问题：

• 如何设计 RESTful API？
• REST endpoint 模式和惯例
• HTTP 方法和状态码

graphql-design

关键词： graphql、schema、query、mutation、connection、relay 解决的问题：

• 如何设计 GraphQL API？
• Schema 设计最佳实践
• 用于分页的 Connection 模式

endpoint-design

关键词： endpoint、route、path、resource、CRUD、openapi 解决的问题：

• 如何构建 API endpoint？
• 这个资源最适合采用哪种 URL 模式？
• RESTful endpoint 命名惯例

url-versioning

关键词： url version、path version、/v1/、/v2/ 解决的问题：

• 如何对 REST API 进行版本控制？
• 基于 URL 的 API 版本控制

header-versioning

关键词： header version、X-API-Version、content negotiation 解决的问题：

• 整洁的 URL 版本控制
• 基于 Header 的 API 版本

deprecation

关键词： deprecation、sunset、version lifecycle、backward compatible 解决的问题：

• 如何弃用 API 版本？
• 版本 Sunset 策略
• 破坏性与非破坏性变更

problem-details

关键词： problem details、RFC 9457、RFC 7807、structured error、application/problem+json 解决的问题：

• 如何规范化 API 错误响应？
• API 错误应采用什么格式？

agent-facing-errors

关键词： agent error、AI agent、retryable、retry_after、error_category、content negotiation、accept header、token efficient、machine readable 解决的问题：

• 如何为 AI Agent 消费者设计错误响应？
• 如何降低错误响应的 token 成本？
• 如何实现确定性的 Agent 错误处理？
• 如何为 Agent、浏览器和大模型进行内容协商？

validation-errors

关键词： validation、field error、422、unprocessable、pydantic 解决的问题：

• 如何处理 API 中的验证错误？
• 字段级错误响应

error-registry

关键词： error registry、problem types、error catalog、error codes 解决的问题：

• 如何记录所有 API 错误？
• 错误类型管理