136 lines
5.0 KiB
Markdown
136 lines
5.0 KiB
Markdown
|
||
# 前端 API 定义规范（REST 风格）
|
||
|
||
> 版本：v1.0
|
||
> 日期：2025-07-01
|
||
> 风格：**RESTful**
|
||
> 适用范围：Vue3 / React / 模块化 JS 项目
|
||
> 目标：提升接口命名一致性，增强可维护性与可读性
|
||
|
||
---
|
||
|
||
## 🌐 RESTful 命名规范
|
||
|
||
REST（Representational 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` |
|
||
|
||
---
|
||
|