ocdp v1
This commit is contained in:
mangomqy
189
docs/archive/root-cleanup/API_NAMING_CONVENTION_FIX.md
Normal file
189
docs/archive/root-cleanup/API_NAMING_CONVENTION_FIX.md
Normal file
@ -0,0 +1,189 @@
|
||||
# API 命名规范统一修复总结
|
||||
|
||||
## 📋 问题描述
|
||||
|
||||
前后端 API 字段命名风格不一致，导致前后端交互失败：
|
||||
|
||||
- **后端 Go JSON tags**: 使用 `snake_case` (如 `cluster_id`, `ca_data`)
|
||||
- **OpenAPI 规范**: 使用 `camelCase` (如 `clusterId`, `caData`)
|
||||
- **前端生成代码**: 使用 `camelCase`，与后端实际返回的JSON不匹配
|
||||
- **前端手写代码**: 为了临时修复，手动使用 `snake_case`
|
||||
|
||||
## ✅ 解决方案
|
||||
|
||||
**选择方案B**: 统一使用 `snake_case` 作为业务数据字段命名规范
|
||||
|
||||
### 命名规范标准
|
||||
|
||||
1. **OpenAPI 自身规范字段**: 保持 `camelCase` (如 `operationId`, `requestBody`)
|
||||
2. **业务数据字段**: 统一使用 `snake_case` (与后端 Go JSON tags 一致)
|
||||
|
||||
### 优势
|
||||
|
||||
- ✅ 保持后端代码不变，降低改动成本
|
||||
- ✅ Go 的 JSON 序列化默认就是字段名，使用 snake_case 更符合 Go 生态
|
||||
- ✅ 前端自动生成的代码与后端完全匹配
|
||||
- ✅ 无需手动维护类型定义
|
||||
|
||||
## 🔧 修改内容
|
||||
|
||||
### 1. 后端 DTO (保持不变)
|
||||
|
||||
```go
|
||||
// backend/internal/adapter/input/http/dto/cluster_dto.go
|
||||
type CreateClusterRequest struct {
|
||||
Name string `json:"name" binding:"required"`
|
||||
Host string `json:"host" binding:"required"`
|
||||
CAData string `json:"ca_data"` // ✅ snake_case
|
||||
CertData string `json:"cert_data"` // ✅ snake_case
|
||||
KeyData string `json:"key_data"` // ✅ snake_case
|
||||
Token string `json:"token"`
|
||||
Description string `json:"description"`
|
||||
}
|
||||
|
||||
type ClusterResponse struct {
|
||||
ID string `json:"id"`
|
||||
Name string `json:"name"`
|
||||
// ...
|
||||
CreatedAt string `json:"created_at"` // ✅ snake_case
|
||||
UpdatedAt string `json:"updated_at"` // ✅ snake_case
|
||||
}
|
||||
```
|
||||
|
||||
### 2. OpenAPI 规范修改
|
||||
|
||||
**修改文件**: `backend/docs/openapi.yaml`
|
||||
|
||||
#### 修改的 Schema：
|
||||
|
||||
1. **CreateClusterRequest**
|
||||
- `caData` → `ca_data`
|
||||
- `certData` → `cert_data`
|
||||
- `keyData` → `key_data`
|
||||
|
||||
2. **UpdateClusterRequest**
|
||||
- `caData` → `ca_data`
|
||||
- `certData` → `cert_data`
|
||||
- `keyData` → `key_data`
|
||||
|
||||
3. **ClusterResponse**
|
||||
- `createdAt` → `created_at`
|
||||
- `updatedAt` → `updated_at`
|
||||
|
||||
4. **RegistryResponse**
|
||||
- `createdAt` → `created_at`
|
||||
- `updatedAt` → `updated_at`
|
||||
|
||||
5. **UserResponse**
|
||||
- `createdAt` → `created_at`
|
||||
- `updatedAt` → `updated_at`
|
||||
|
||||
6. **InstanceResponse**
|
||||
- `clusterId` → `cluster_id` ✅
|
||||
- `registryId` → `registry_id` ✅ (新增字段)
|
||||
- `repository` ✅ (新增字段)
|
||||
|
||||
### 3. 前端生成代码
|
||||
|
||||
重新生成前端 TypeScript API 客户端：
|
||||
|
||||
```bash
|
||||
bash scripts/sync-openapi-frontend.sh
|
||||
```
|
||||
|
||||
**生成结果**:
|
||||
- ✅ 7 个 API 文件
|
||||
- ✅ 25 个 Model 文件
|
||||
- ✅ 完全匹配后端 JSON 字段命名
|
||||
|
||||
**示例生成代码**:
|
||||
|
||||
```typescript
|
||||
// frontend/src/api/generated/models/create-cluster-request.ts
|
||||
export interface CreateClusterRequest {
|
||||
'name': string;
|
||||
'host': string;
|
||||
'ca_data'?: string; // ✅ snake_case
|
||||
'cert_data'?: string; // ✅ snake_case
|
||||
'key_data'?: string; // ✅ snake_case
|
||||
'token'?: string;
|
||||
}
|
||||
|
||||
// frontend/src/api/generated/models/instance-response.ts
|
||||
export interface InstanceResponse {
|
||||
'id'?: string;
|
||||
'name'?: string;
|
||||
'namespace'?: string;
|
||||
'cluster_id'?: string; // ✅ snake_case
|
||||
'registry_id'?: string; // ✅ snake_case
|
||||
'repository'?: string;
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
## 📊 影响范围
|
||||
|
||||
### 已修改
|
||||
|
||||
1. ✅ `backend/docs/openapi.yaml` - OpenAPI 规范
|
||||
2. ✅ `frontend/src/api/generated/*` - 自动生成的 TypeScript 代码
|
||||
|
||||
### 无需修改
|
||||
|
||||
1. ✅ 后端 Go DTO 代码 - 保持原有 snake_case
|
||||
2. ✅ 前端手写的临时修复代码 - 现在可以使用生成的代码替换
|
||||
|
||||
## 🎯 后续工作
|
||||
|
||||
### 可选优化（前端）
|
||||
|
||||
前端中手写的类型定义现在可以删除，直接使用生成的代码：
|
||||
|
||||
**需要清理的文件**:
|
||||
- `frontend/src/core/types/index.ts` - 包含手写的 snake_case 类型
|
||||
- `frontend/src/core/api/instance.api.ts` - 包含手写的接口定义
|
||||
- `frontend/src/core/api/unified-api.ts` - 包含手写的接口定义
|
||||
|
||||
**推荐做法**:
|
||||
直接导入并使用自动生成的类型：
|
||||
```typescript
|
||||
import {
|
||||
ClusterResponse,
|
||||
CreateClusterRequest,
|
||||
InstanceResponse
|
||||
} from '@/api/generated';
|
||||
```
|
||||
|
||||
## ✅ 验证
|
||||
|
||||
### 字段命名一致性检查
|
||||
|
||||
| 字段 | 后端 JSON | OpenAPI | 前端生成 | 状态 |
|
||||
|------|-----------|---------|----------|------|
|
||||
| `ca_data` | ✅ | ✅ | ✅ | 一致 |
|
||||
| `cert_data` | ✅ | ✅ | ✅ | 一致 |
|
||||
| `key_data` | ✅ | ✅ | ✅ | 一致 |
|
||||
| `cluster_id` | ✅ | ✅ | ✅ | 一致 |
|
||||
| `registry_id` | ✅ | ✅ | ✅ | 一致 |
|
||||
| `created_at` | ✅ | ✅ | ✅ | 一致 |
|
||||
| `updated_at` | ✅ | ✅ | ✅ | 一致 |
|
||||
|
||||
## 📝 注意事项
|
||||
|
||||
1. **OpenAPI 规范字段仍使用 camelCase**: 如 `operationId`, `requestBody` 等元字段
|
||||
2. **业务数据字段统一 snake_case**: 所有 schemas 中的属性
|
||||
3. **前端需更新代码**: 如果有直接使用手写类型的地方，需要切换到生成的类型
|
||||
|
||||
## 🔗 相关文件
|
||||
|
||||
- OpenAPI 规范: `backend/docs/openapi.yaml`
|
||||
- 生成脚本: `scripts/sync-openapi-frontend.sh`
|
||||
- 前端生成代码: `frontend/src/api/generated/`
|
||||
- 后端 DTO: `backend/internal/adapter/input/http/dto/`
|
||||
|
||||
---
|
||||
|
||||
**修复日期**: 2025-11-10
|
||||
**修复人**: AI Assistant
|
||||
**影响版本**: OCDP v1.0.0
|
||||
|
||||
Reference in New Issue
Block a user