164 lines
4.5 KiB
Markdown
164 lines
4.5 KiB
Markdown
# 产品API配置管理功能说明
|
||
|
||
## 功能概述
|
||
|
||
产品API配置管理功能允许管理员为每个产品配置API接口的请求参数、响应字段和响应示例，这些配置将用于前端的在线调试功能。
|
||
|
||
## 功能特性
|
||
|
||
### 1. 请求参数配置
|
||
- **参数名称**: 显示给用户的参数名称（如：姓名）
|
||
- **字段名**: API接口中使用的字段名（如：name）
|
||
- **参数类型**: 支持文本、数字、密码、邮箱、手机号、身份证等类型
|
||
- **是否必填**: 标识该参数是否为必填项
|
||
- **参数示例**: 提供给用户的输入示例
|
||
- **验证规则**: 正则表达式验证规则
|
||
- **参数描述**: 参数的详细说明
|
||
|
||
### 2. 响应字段配置
|
||
- **字段名称**: 显示给用户的字段名称（如：姓名）
|
||
- **字段路径**: JSON响应中的字段路径（如：data.name）
|
||
- **字段类型**: 支持字符串、数字、布尔值、对象、数组等类型
|
||
- **是否必填**: 标识该字段是否在响应中必填
|
||
- **字段示例**: 字段的示例值
|
||
- **字段描述**: 字段的详细说明
|
||
|
||
### 3. 响应示例
|
||
- **JSON格式**: 完整的API响应示例
|
||
- **实时验证**: 确保输入的JSON格式正确
|
||
- **格式化显示**: 自动格式化JSON内容
|
||
|
||
## 使用方法
|
||
|
||
### 1. 访问产品管理页面
|
||
1. 登录管理员账户
|
||
2. 进入"产品管理"页面
|
||
3. 在产品列表中找到需要配置的产品
|
||
|
||
### 2. 配置API
|
||
1. 点击产品行的"配置API"按钮
|
||
2. 在弹出的配置窗口中：
|
||
- 查看产品基本信息
|
||
- 添加/编辑请求参数
|
||
- 添加/编辑响应字段
|
||
- 输入JSON响应示例
|
||
3. 点击"创建"或"更新"保存配置
|
||
|
||
### 3. 配置示例
|
||
|
||
#### 请求参数配置示例
|
||
```json
|
||
[
|
||
{
|
||
"name": "姓名",
|
||
"field": "name",
|
||
"type": "text",
|
||
"required": true,
|
||
"description": "用户真实姓名",
|
||
"example": "张三",
|
||
"validation": "^[\\u4e00-\\u9fa5]{2,4}$"
|
||
},
|
||
{
|
||
"name": "身份证号",
|
||
"field": "id_card",
|
||
"type": "idcard",
|
||
"required": true,
|
||
"description": "用户身份证号码",
|
||
"example": "110101199001011234",
|
||
"validation": "^[1-9]\\d{5}(18|19|20)\\d{2}((0[1-9])|(1[0-2]))(([0-2][1-9])|10|20|30|31)\\d{3}[0-9Xx]$"
|
||
}
|
||
]
|
||
```
|
||
|
||
#### 响应字段配置示例
|
||
```json
|
||
[
|
||
{
|
||
"name": "结果",
|
||
"path": "result",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "查询结果",
|
||
"example": "success"
|
||
},
|
||
{
|
||
"name": "数据",
|
||
"path": "data",
|
||
"type": "object",
|
||
"required": false,
|
||
"description": "查询结果数据",
|
||
"example": "{}"
|
||
}
|
||
]
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
{
|
||
"result": "success",
|
||
"code": 200,
|
||
"message": "查询成功",
|
||
"data": {
|
||
"name": "张三",
|
||
"id_card": "110101199001011234",
|
||
"mobile": "13800138000",
|
||
"status": "正常",
|
||
"query_time": "2024-01-01 12:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 技术实现
|
||
|
||
### 后端架构
|
||
- **实体层**: `ProductApiConfig` 实体
|
||
- **仓库层**: `ProductApiConfigRepository` 接口和实现
|
||
- **领域服务层**: `ProductApiConfigService` 业务逻辑
|
||
- **应用服务层**: `ProductApiConfigApplicationService` 业务流程
|
||
- **HTTP层**: `ProductAdminHandler` 接口处理
|
||
|
||
### 前端架构
|
||
- **组件**: `ProductApiConfigDialog.vue` 配置弹窗
|
||
- **页面**: 集成到产品管理页面
|
||
- **API**: 通过 `productAdminApi` 调用后端接口
|
||
|
||
### 数据库设计
|
||
```sql
|
||
CREATE TABLE product_api_configs (
|
||
id VARCHAR(36) PRIMARY KEY,
|
||
product_id VARCHAR(36) NOT NULL UNIQUE,
|
||
request_params JSON NOT NULL,
|
||
response_fields JSON NOT NULL,
|
||
response_example JSON NOT NULL,
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
deleted_at TIMESTAMP NULL,
|
||
FOREIGN KEY (product_id) REFERENCES products(id)
|
||
);
|
||
```
|
||
|
||
## 初始化脚本
|
||
|
||
项目提供了初始化脚本 `scripts/init_product_api_configs.go`，可以为现有产品创建默认的API配置：
|
||
|
||
```bash
|
||
cd tyapi-server-gin
|
||
go run scripts/init_product_api_configs.go
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **唯一性**: 每个产品只能有一个API配置
|
||
2. **JSON格式**: 响应示例必须是有效的JSON格式
|
||
3. **字段路径**: 响应字段路径使用点号分隔（如：data.name）
|
||
4. **验证规则**: 支持正则表达式验证规则
|
||
5. **权限控制**: 只有管理员可以配置API
|
||
|
||
## 扩展功能
|
||
|
||
未来可以考虑添加的功能：
|
||
1. **配置模板**: 提供常用的配置模板
|
||
2. **批量导入**: 支持批量导入配置
|
||
3. **版本管理**: 支持配置版本管理
|
||
4. **测试功能**: 集成API测试功能
|
||
5. **文档生成**: 自动生成API文档 |