136 lines
5.0 KiB
Markdown
Raw Permalink Normal View History

2025-07-02 17:10:19 +08:00
# 前端 API 定义规范REST 风格)
> 版本v1.0
> 日期2025-07-01
> 风格:**RESTful**
> 适用范围Vue3 / React / 模块化 JS 项目
> 目标:提升接口命名一致性,增强可维护性与可读性
---
## 🌐 RESTful 命名规范
RESTRepresentational State Transfer强调以资源为中心的接口设计以下为规范核心
### ✅ 基本动词与 HTTP 方法对应
| 动作 | HTTP 方法 | 路径示例 | 命名示例(函数) |
|--------------|------------|-------------------------------|---------------------------|
| 获取列表 | GET | `/users` | `fetchUserList` |
| 获取详情 | GET | `/users/:id` | `getUserById` |
| 创建 | POST | `/users` | `createUser` |
| 修改 | PUT/PATCH | `/users/:id` | `updateUser` |
| 删除 | DELETE | `/users/:id` | `deleteUserById` |
| 导出 | GET | `/users/export` | `exportUserExcel` |
| 上传 | POST | `/files/upload` | `uploadFile` |
---
## 📁 文件组织结构
```bash
src/
├── apis/
│ ├── landResourceManagement/ # 土地资源管理
│ │ ├── plantingPlan/ # 种植规划
│ │ │ ├── index.js
│ │ ├── operationRecord/ # 作业记录
│ │ │ ├── index.js
│ │ ├── landIllegal/ # 土地违法处理
│ │ │ ├── index.js
│ │ ├── landManagement/ # 土地管理
│ │ │ ├── index.js
│ │ ├── landInspection/ # 土地巡查
│ │ │ ├── index.js
│ │ ├── gridManagement/ # 网格管理
│ │ │ ├── index.js
│ │ ├── gridMemberManagement/ # 网格员管理
│ │ │ ├── index.js
│ │ ├── basicInfoMaintenance/ # 基础信息维护
│ │ │ ├── index.js
│ │ ├── cropsManagement/ # 种植作物
│ │ │ ├── index.js
│ │ ├── index.js # 土地资源管理模块统一入口
│ ├── productionEntityManagement/ # 生产经营主体管理
│ │ ├── index.js
│ ├── inputManagement/ # 投入品管理
│ │ ├── index.js
│ ├── productTraceability/ # 农产品溯源
│ │ ├── index.js
│ ├── index.js # 项目统一入口文件
├── utils/
│ ├── axios.js # 封装的请求工具
```
---
## 🧱 函数命名规范
接口定义应以 **动词+资源名** 格式命名函数(驼峰式 camelCase
```js
// 用户模块 API 示例
import request from '@/utils/request';
export function fetchUserList(params) {
return request('/api/users', { method: 'GET', params });
}
export function getUserById(id) {
return request(`/api/users/${id}`, { method: 'GET' });
}
export function createUser(data) {
return request('/api/users', { method: 'POST', data });
}
export function updateUser(id, data) {
return request(`/api/users/${id}`, { method: 'PUT', data });
}
export function deleteUserById(id) {
return request(`/api/users/${id}`, { method: 'DELETE' });
}
```
---
## 🧠 组件方法命名建议
组件内部方法UI逻辑处理请统一以 `handle` 前缀区分,避免与 API 冲突:
```js
const handleAddUser = () => { ... };
const handleEditUser = (row) => { ... };
const handleDeleteUser = (id) => { ... };
const handleExportExcel = () => { ... };
```
---
## 🚫 命名反例
| 错误命名 | 问题说明 | 推荐命名 |
|------------------|----------------------------------------|--------------------------|
| `listUser` | 动词语义模糊 | `fetchUserList` |
| `editUserById` | 与 REST 风格不符 | `updateUser` |
| `addOrEditUser` | 接口职责不清晰 | `createUser``updateUser` |
| `removeUser` | 与 HTTP 方法不一致 | `deleteUserById` |
---
## 🧾 附录:接口语义对照表
| 类型 | HTTP 方法 | REST URI 示例 | 函数命名示例 |
|-------------|------------|---------------------------|--------------------------|
| 查询列表 | GET | `/entities` | `fetchEntityList` |
| 查询详情 | GET | `/entities/:id` | `getEntityById` |
| 新增 | POST | `/entities` | `createEntity` |
| 修改 | PUT | `/entities/:id` | `updateEntity` |
| 删除 | DELETE | `/entities/:id` | `deleteEntityById` |
| 导出 | GET | `/entities/export` | `exportEntityExcel` |
---