22 lines
1.7 KiB
Markdown
22 lines
1.7 KiB
Markdown
---
|
|
name: design-api
|
|
description: 基于项目需求、现有契约和对应版本官方规范设计或评审 HTTP API。适用于资源边界、方法、状态码、请求响应、兼容和 OpenAPI 契约；前后端字段对接、后端整体设计或直接编码不应触发。
|
|
---
|
|
|
|
# API 设计
|
|
|
|
先确认项目协议、OpenAPI 版本、已有接口风格和兼容边界，再形成可实现、可验证的契约。
|
|
|
|
## 工作流
|
|
|
|
1. 读取 `.craftkit/project.json`、适用规范、现有契约和调用方证据。
|
|
2. 明确资源、动作、幂等性、认证授权、输入、输出和错误语义。
|
|
3. 方法、状态码、缓存、条件请求和重试语义以 [官方来源](references/sources.md) 及项目版本为依据。
|
|
4. 输出路径与方法、参数位置、请求响应模型、错误、兼容、弃用和测试清单。
|
|
5. 默认在对话中输出；用户要求保存设计文档时读取 `.craftkit/project.json` 的 `documents` 配置，过程设计使用 `workRoot`，共享设计使用 `designRoot`，不改变接口自身的路径设计。
|
|
|
|
落盘前检索同主题的需求、设计、规范或知识，优先更新已有权威文档。共享长期文档新建或实质修改后按 `.craftkit/standards/document-maintenance.md` 更新审核状态；排版和错字修正不改变状态。`r`n`r`n写入后在 `workRoot/<task>/task.json` 登记本次创建、更新或引用的文档及 `relationship`；已有记录时保守合并。关联旧文档不转移所有权，也不产生删除权限；不修改项目级默认配置。
|
|
6. 未确认的业务规则和框架封装列为待确认，不生成实现代码。
|
|
|
|
项目规则高于公共建议；不得默认最新 OpenAPI 版本或把内部接口模式写成通用规则。
|