77 lines
1.8 KiB
Markdown
77 lines
1.8 KiB
Markdown
# 07 API 规范
|
||
|
||
## 路由
|
||
|
||
RESTful，统一前缀 `/api/v1/`。
|
||
|
||
```
|
||
GET /api/v1/warehouses
|
||
GET /api/v1/skus
|
||
GET /api/v1/inventory
|
||
|
||
POST /api/v1/inbounds
|
||
POST /api/v1/inbounds/{inbound_no}/receive
|
||
POST /api/v1/inbounds/{inbound_no}/putaway
|
||
|
||
GET /api/v1/outbounds
|
||
POST /api/v1/outbounds/{outbound_no}/allocate
|
||
POST /api/v1/outbounds/{outbound_no}/pick
|
||
POST /api/v1/outbounds/{outbound_no}/pack
|
||
POST /api/v1/outbounds/{outbound_no}/ship
|
||
```
|
||
|
||
要点：
|
||
|
||
- 资源名使用复数。
|
||
- 路由参数优先使用业务编码（`inbound_no`、`outbound_no`），而非自增 ID。
|
||
- 业务动作（状态流转）使用 `POST /{resource}/{code}/{action}`。
|
||
- 认证使用 Laravel Sanctum，授权使用 Policies / Gates。
|
||
|
||
## 统一返回格式
|
||
|
||
不要每个 Controller 自己定义一套返回结构。
|
||
|
||
成功：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "OK",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
失败：
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "操作失败",
|
||
"errors": {}
|
||
}
|
||
```
|
||
|
||
分页列表的 `data` 是当前页记录，分页信息放在同级 `meta`。所有列表接口都走 `ApiResponse::paginated()`。
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "OK",
|
||
"data": [],
|
||
"meta": {
|
||
"current_page": 1,
|
||
"per_page": 20,
|
||
"total": 0,
|
||
"last_page": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
默认每页 20 条，最大 100 条。失败响应的 `errors` 没有内容时是 JSON 对象 `{}`，不是数组。
|
||
|
||
`/api/*` 的异常由统一异常处理转成失败格式，不返回框架堆栈。响应头 `X-Request-Id` 贯穿本次请求；客户端传入的值仅在字母、数字、下划线、连字符且不超过 64 位时沿用。
|
||
|
||
## 内部 API（Python Service）
|
||
|
||
Laravel 调用 Python 的内部接口统一使用 `/internal/v1/` 前缀，见 [11-py-service.md](./11-py-service.md)。
|