【Uniapp】代码规范五：API管理规范

1. API 结构

• 目录结构：将API相关代码放在一个专门的目录中，例如 src/api，并按功能模块划分子目录，确保目录层次清晰，易于管理。

• 示例：

src/
└── api/
    ├── user.js         // 用户相关的API
    ├── product.js      // 产品相关的API
    ├── order.js        // 订单相关的API

2. API 文件格式

• 文件命名：使用小写字母加下划线（snake_case）命名文件，例如 user_api.js，以提高可读性。

• 导出方式：统一使用命名导出，以便按需导入，提高代码的可维护性和灵活性。

  示例：

// user.js
export const fetchUserData = async (userId) => {
    // 实现获取用户数据的逻辑
};
​
export const updateUser = async (userId, userData) => {
    // 实现更新用户数据的逻辑
};

3. API 请求处理

• 请求库：统一使用一个请求库，如 axios，并进行封装以提高重用性和可维护性，避免重复代码。

  示例：

import axios from 'axios';
​
const apiClient = axios.create({
    baseURL: 'https://api.example.com',
    timeout: 10000,
    headers: {
        'Content-Type': 'application/json',
    },
});
​
export const fetchUserData = async (userId) => {
    return apiClient.get(`/users/${userId}`);
};

4. API 异常处理

• 错误处理：在API请求中处理异常，确保能够捕获并返回有用的错误信息。使用 try-catch 块捕获异常，并返回标准的错误响应格式，以便前端能够做出相应处理。

  示例：

export const fetchUserData = async (userId) => {
    try {
        const response = await apiClient.get(`/users/${userId}`);
        return response.data;
    } catch (error) {
        // 记录错误并返回标准格式
        console.error('API请求失败:', error);
        throw new Error('获取用户数据失败');
    }
};

5. API 版本管理

• 版本管理：在URL中包含API版本号，例如 /v1/users，以便于在未来进行版本升级。通过创建一个 version 变量，方便管理和更新API版本。

  示例：

const API_VERSION = 'v1';
const apiClient = axios.create({
    baseURL: `https://api.example.com/${API_VERSION}`,
});

6. API 响应格式

• 统一响应格式：定义统一的响应格式，包括状态码、消息和数据。确保所有API返回相同结构的响应，以便前端处理和错误显示一致。

  示例：

{
    "status": "success",
    "data": {
        // 实际数据
    },
    "message": "请求成功"
}

7. 文档与注释

• 注释：使用JSDoc格式为每个API函数添加注释，描述其功能、参数和返回值，提升代码可读性和可维护性。

  示例：

/**
 * 获取用户数据
 * @param {string} userId - 用户的唯一标识
 * @returns {Promise<object>} - 返回用户数据
 */
export const fetchUserData = async (userId) => {
    // ...
};

• API 文档：使用工具（如Swagger或Postman）生成API文档，确保团队成员能够方便地查看API的使用方法、请求参数和响应示例，促进团队协作。

8. 测试

• API 测试：使用测试框架（如Jest或Mocha）编写单元测试和集成测试，确保API的可靠性和稳定性。编写测试用例时，确保覆盖正常情况和异常情况。

  示例：

import { fetchUserData } from './user';
​
test('fetchUserData should return user data', async () => {
    const data = await fetchUserData('123');
    expect(data).toHaveProperty('id', '123');
});
​
test('fetchUserData should throw error for invalid userId', async () => {
    await expect(fetchUserData('invalid')).rejects.toThrow('获取用户数据失败');
});

通过遵循这些API管理规范，可以提高项目的可维护性、一致性和可读性，便于团队协作和后续开发。确保每位开发人员都理解并遵循这些规范，以提升整体开发效率和代码质量。