143 lines
2.7 KiB
Markdown
143 lines
2.7 KiB
Markdown
# API / 模块合约
|
|
|
|
> 本文定义后端 API、本地模块、CLI 参数或事件合约的目标形状。
|
|
> 实现前可细化，但不要在代码里另起一套不兼容接口。
|
|
|
|
如果项目没有后端 API，删除不适用的小节，改成本地模块接口、CLI 参数或事件合约。不要默认所有项目都有 REST 后端。
|
|
|
|
## 通用约定
|
|
|
|
- 传输：【JSON over HTTPS / GraphQL / gRPC / 本地函数调用】。
|
|
- 鉴权：【Session Cookie / Bearer Token / 无】。
|
|
- 请求体和响应体编码：【UTF-8 JSON】。
|
|
- 时间格式：【ISO 8601 / Unix timestamp】。
|
|
- 未登录访问需要权限的接口时返回：【401 / 403】。
|
|
|
|
通用错误响应：
|
|
|
|
```json
|
|
{
|
|
"error": {
|
|
"code": "bad_request",
|
|
"message": "请求参数不正确"
|
|
}
|
|
}
|
|
```
|
|
|
|
## 账号
|
|
|
|
### `POST /api/auth/login`
|
|
|
|
请求：
|
|
|
|
```json
|
|
{
|
|
"email": "user@example.com",
|
|
"password": "password"
|
|
}
|
|
```
|
|
|
|
成功响应：
|
|
|
|
```json
|
|
{
|
|
"user": {
|
|
"id": 1,
|
|
"email": "user@example.com"
|
|
}
|
|
}
|
|
```
|
|
|
|
## 核心资源
|
|
|
|
把项目的核心资源按 REST 或其他风格写清楚。
|
|
|
|
### `GET /api/items`
|
|
|
|
成功响应：
|
|
|
|
```json
|
|
{
|
|
"items": [
|
|
{
|
|
"id": 1,
|
|
"name": "示例"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### `POST /api/items`
|
|
|
|
请求：
|
|
|
|
```json
|
|
{
|
|
"name": "示例"
|
|
}
|
|
```
|
|
|
|
成功响应返回新增资源。
|
|
|
|
## 无后端项目替代写法
|
|
|
|
用于桌面工具、CLI、本地自动化脚本、纯前端本地应用等没有后端服务的项目。
|
|
|
|
### 本地模块合约
|
|
|
|
```ts
|
|
type Input = {
|
|
sourcePath: string;
|
|
options: {
|
|
dryRun: boolean;
|
|
};
|
|
};
|
|
|
|
type Result = {
|
|
ok: boolean;
|
|
outputPath?: string;
|
|
errors: Array<{
|
|
code: string;
|
|
message: string;
|
|
}>;
|
|
};
|
|
```
|
|
|
|
需要写清楚：
|
|
|
|
- 模块入口函数：【函数名 / 文件路径】。
|
|
- 输入字段：【字段、类型、必填、默认值】。
|
|
- 输出字段：【成功结果、失败结果、错误码】。
|
|
- 副作用：【读写哪些文件、调用哪些系统能力、是否联网】。
|
|
|
|
### CLI 参数合约
|
|
|
|
```bash
|
|
【命令】 --input 【路径】 --output 【路径】 --dry-run
|
|
```
|
|
|
|
需要写清楚：
|
|
|
|
- 必填参数和可选参数。
|
|
- 默认值。
|
|
- 退出码含义。
|
|
- 标准输出和错误输出格式。
|
|
|
|
### 事件合约
|
|
|
|
适用于桌面 UI、浏览器本地状态、插件或自动化流程。
|
|
|
|
| 事件 | 触发时机 | 负载 | 结果 |
|
|
| --- | --- | --- | --- |
|
|
| 【event.name】 | 【用户动作 / 系统动作】 | 【字段】 | 【状态变化】 |
|
|
|
|
需要写清楚事件来源、负载字段、状态变化和失败处理。
|
|
|
|
## 待实现时确认
|
|
|
|
- 参数校验规则。
|
|
- 分页、排序、筛选方式。
|
|
- 重复提交是否幂等。
|
|
- 错误码枚举。
|
|
- 鉴权过期时间和刷新策略。
|
|
- 无后端项目的模块入口、CLI 参数、事件负载和副作用边界。 |