「简记往来」开发历程系列：API设计——RESTful接口在礼账场景中的实践
一、资源设计
RESTful API的核心是“资源”。简记往来的核心资源：
| 资源 | URL | 说明 |
|---|---|---|
| 账本 | /api/books | 用户创建的账本 |
| 成员 | /api/members | 账本成员 |
| 记录 | /api/records | 礼金记录 |
| 联系人 | /api/contacts | 联系人档案 |
二、HTTP方法映射
| 操作 | HTTP方法 | URL | 说明 |
|---|---|---|---|
| 创建账本 | POST | /api/books | 新建一个账本 |
| 获取账本列表 | GET | /api/books | 获取用户所有账本 |
| 获取账本详情 | GET | /api/books/{id} | 获取单个账本信息 |
| 更新账本 | PUT | /api/books/{id} | 修改账本名称 |
| 删除账本 | DELETE | /api/books/{id} | 解散账本 |
三、状态码规范
| 状态码 | 含义 | 使用场景 |
|---|---|---|
| 200 | OK | 请求成功 |
| 201 | Created | 创建成功 |
| 400 | Bad Request | 参数错误 |
| 401 | Unauthorized | 未登录 |
| 403 | Forbidden | 无权限 |
| 404 | Not Found | 资源不存在 |
| 500 | Internal Server Error | 服务器错误 |
四、错误处理统一格式
所有错误响应使用统一格式：
{"code":40001,"message":"参数缺失：bookId","timestamp":1700000000000}错误码规范：
- 40001-40099：参数错误
- 40100-40199：认证错误
- 40300-40399：权限错误
- 40400-40499：资源不存在
- 50000-50099：服务器错误
五、核心接口示例
创建记录：
POST /api/records Authorization: Bearer {token} { "bookId": "book_xxx", "contactId": "contact_xxx", "type": "receive", "amount": 800, "date": "2026-06-20", "note": "婚礼" }响应：
{"code":0,"data":{"id":"record_xxx","bookId":"book_xxx","contactId":"contact_xxx","type":"receive","amount":800,"date":"2026-06-20","note":"婚礼","createdAt":"2026-06-20T10:00:00Z"}}六、总结
API设计的核心原则：
- 资源命名用复数：
/api/books而不是/api/book - 使用标准HTTP方法：GET/POST/PUT/DELETE
- 状态码语义化：用标准HTTP状态码
- 错误信息清晰：告诉用户哪里错了、怎么改
遵循这些规范，API会更容易维护，也更容易被前端调用。