9213b90d61
- 重构采购审批页面，移除冗余的表单逻辑和校验代码 - 新增基础信息模块自动获取上一车次号功能 - 优化自定义主题配置，统一使用 Taro.pxTransform 处理单位 - 调整页面列表组件的数据加载逻辑，支持分页追加数据 - 优化成本相关组件的价格展示样式，统一字体大小和颜色 - 移除页面中冗余的状态管理和副作用逻辑 - 调整审批页面布局结构，提升用户体验
142 lines
4.4 KiB
Markdown
142 lines
4.4 KiB
Markdown
# API 接口实现规范
|
||
|
||
## 概述
|
||
|
||
本系统采用基于 axios 的 HTTP 客户端来与后端进行通信，所有 API 请求都经过统一的封装和管理。该文档旨在说明如何在系统中添加和使用新的 API 接口。
|
||
|
||
## 核心架构
|
||
|
||
### 1. 请求客户端 (request.ts)
|
||
|
||
系统在 `packages/app-client/src/services/request.ts` 文件中创建了一个全局的 axios 实例，用于处理所有 HTTP 请求。
|
||
|
||
```typescript
|
||
import axios from "axios";
|
||
import Taro from "@tarojs/taro";
|
||
|
||
const request = axios.create({
|
||
baseURL: process.env.TARO_API_DOMAIN,
|
||
});
|
||
```
|
||
|
||
该实例具有以下特性：
|
||
- 设置了基础 URL，从环境变量 `TARO_API_DOMAIN` 获取
|
||
- 包含请求拦截器，自动添加认证信息（如 saToken 和角色信息）
|
||
- 包含响应拦截器，处理通用的响应逻辑（如权限验证、错误提示等）
|
||
|
||
### 2. 请求拦截器
|
||
|
||
在发送请求前，系统会自动添加以下头部信息：
|
||
- `saToken`: 用户的身份认证令牌，从本地存储中获取
|
||
- `Xh-Role-Slug`: 用户当前角色标识，从本地存储中获取
|
||
|
||
### 3. 响应拦截器
|
||
|
||
响应拦截器负责处理通用的业务逻辑：
|
||
- 成功响应时检查是否需要更新本地存储的认证信息
|
||
- 错误响应时根据错误码显示相应提示或执行特定操作（如 401 时跳转登录页）
|
||
|
||
## API 接口组织
|
||
|
||
### 1. 模块划分
|
||
|
||
API 接口按照业务模块进行组织，每个模块对应一个文件：
|
||
- 所有业务 API 存放在 `packages/app-client/src/services/business/` 目录下
|
||
- 每个文件代表一个业务模块（如 [platform.ts](file:///D:/xinfaleisheng/ERPTurbo_Client/packages/app-client/src/services/business/platform.ts)、[user.ts](file:///D:/xinfaleisheng/ERPTurbo_Client/packages/app-client/src/services/business/user.ts) 等）
|
||
- 每个模块导出一组相关的 API 函数
|
||
|
||
### 2. 接口定义格式
|
||
|
||
每个 API 函数遵循统一的格式：
|
||
|
||
```typescript
|
||
/** 接口说明 GET|POST|PUT|DELETE /api/path */
|
||
export async function apiFunctionName(
|
||
// 参数类型定义
|
||
params: BusinessAPI.paramsType,
|
||
options?: { [key: string]: any },
|
||
) {
|
||
return request<BusinessAPI.ResponseType>("/api/path", {
|
||
method: "GET|POST|PUT|DELETE",
|
||
// 根据请求方法设置 headers、params 或 data
|
||
...(options || {}),
|
||
});
|
||
}
|
||
```
|
||
|
||
### 3. 模块导出
|
||
|
||
所有业务模块在 `packages/app-client/src/services/business/index.ts` 中统一导出：
|
||
|
||
```typescript
|
||
import * as moduleName from "./moduleName";
|
||
export default {
|
||
moduleName,
|
||
// ...
|
||
};
|
||
```
|
||
|
||
## 添加新接口步骤
|
||
|
||
### 1. 确定业务模块
|
||
|
||
首先确定新接口属于哪个业务模块，如果现有模块都不合适，则需要创建新的模块文件。
|
||
|
||
### 2. 定义数据类型
|
||
|
||
在 `typings.d.ts` 文件中定义接口所需的请求参数类型和响应数据类型。
|
||
|
||
### 3. 编写接口函数
|
||
|
||
在对应的模块文件中添加新的接口函数，参考以下模板：
|
||
|
||
```typescript
|
||
/** 接口说明 动作 /api/path */
|
||
export async function functionName(
|
||
// 根据实际参数类型修改
|
||
body: BusinessAPI.RequestType,
|
||
options?: { [key: string]: any },
|
||
) {
|
||
// 根据实际响应类型修改
|
||
return request<BusinessAPI.ResponseType>("/api/path", {
|
||
method: "POST", // 根据实际情况修改为 POST/GET/PUT/DELETE
|
||
headers: {
|
||
"Content-Type": "application/json",
|
||
},
|
||
data: body, // GET 请求使用 params，其他请求使用 data
|
||
...(options || {}),
|
||
});
|
||
}
|
||
```
|
||
|
||
### 4. 导出模块
|
||
|
||
确保在 `packages/app-client/src/services/business/index.ts` 中导出了包含新接口的模块。
|
||
|
||
## 使用示例
|
||
|
||
在组件或其他服务中使用 API 接口：
|
||
|
||
```typescript
|
||
import businessServices from "@/services/business";
|
||
|
||
// 调用平台列表接口
|
||
const {data: {data: platformList}} = await businessServices.platform.listPlatform({
|
||
// 参数
|
||
});
|
||
|
||
// 调用创建平台接口
|
||
const {data: {data: platform}} = await businessServices.platform.createPlatform({
|
||
// 数据体
|
||
});
|
||
```
|
||
|
||
## 最佳实践
|
||
|
||
1. **类型安全**: 始终使用 TypeScript 类型定义请求参数和响应数据
|
||
2. **错误处理**: 在调用 API 的地方适当处理可能发生的错误
|
||
3. **命名规范**: 接口函数名应该清晰表达其功能，通常采用动词+名词的形式
|
||
4. **注释说明**: 每个接口函数都需要添加注释说明接口用途和路径
|
||
5. **统一管理**: 所有 API 接口都应该按业务模块分类管理
|
||
6. **避免重复**: 相似的接口可以复用已有模式，保持一致性
|