# 前端 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` | ---