19 lines
1.0 KiB
Markdown
19 lines
1.0 KiB
Markdown
---
|
|
name: design-api
|
|
description: 基于项目需求、现有契约和对应版本官方规范设计或评审 HTTP API。适用于资源边界、方法、状态码、请求响应、兼容和 OpenAPI 契约；前后端字段对接、后端整体设计或直接编码不应触发。
|
|
---
|
|
|
|
# API 设计
|
|
|
|
先确认项目协议、OpenAPI 版本、已有接口风格和兼容边界，再形成可实现、可验证的契约。
|
|
|
|
## 工作流
|
|
|
|
1. 读取 `.craftkit/project.json`、适用规范、现有契约和调用方证据。
|
|
2. 明确资源、动作、幂等性、认证授权、输入、输出和错误语义。
|
|
3. 方法、状态码、缓存、条件请求和重试语义以 [官方来源](references/sources.md) 及项目版本为依据。
|
|
4. 输出路径与方法、参数位置、请求响应模型、错误、兼容、弃用和测试清单。
|
|
5. 未确认的业务规则和框架封装列为待确认，不生成实现代码。
|
|
|
|
项目规则高于公共建议；不得默认最新 OpenAPI 版本或把内部接口模式写成通用规则。
|