OCDP/ocdp-go

Fork 0

Files

mangomqy c5e51ed069 ocdp v1

2025-11-13 02:54:06 +00:00

5.3 KiB

Raw Blame History

API 命名规范统一修复总结

📋 问题描述

前后端 API 字段命名风格不一致，导致前后端交互失败：

后端 Go JSON tags: 使用 snake_case (如 cluster_id, ca_data)
OpenAPI 规范: 使用 camelCase (如 clusterId, caData)
前端生成代码: 使用 camelCase，与后端实际返回的JSON不匹配
前端手写代码: 为了临时修复，手动使用 snake_case

✅ 解决方案

选择方案B: 统一使用 snake_case 作为业务数据字段命名规范

命名规范标准

OpenAPI 自身规范字段: 保持 camelCase (如 operationId, requestBody)
业务数据字段: 统一使用 snake_case (与后端 Go JSON tags 一致)

优势

✅ 保持后端代码不变，降低改动成本
✅ Go 的 JSON 序列化默认就是字段名，使用 snake_case 更符合 Go 生态
✅ 前端自动生成的代码与后端完全匹配
✅ 无需手动维护类型定义

🔧 修改内容

1. 后端 DTO (保持不变)

// 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：

CreateClusterRequest
- caData → ca_data
- certData → cert_data
- keyData → key_data
UpdateClusterRequest
- caData → ca_data
- certData → cert_data
- keyData → key_data
ClusterResponse
- createdAt → created_at
- updatedAt → updated_at
RegistryResponse
- createdAt → created_at
- updatedAt → updated_at
UserResponse
- createdAt → created_at
- updatedAt → updated_at
InstanceResponse
- clusterId → cluster_id ✅
- registryId → registry_id ✅ (新增字段)
- repository ✅ (新增字段)

3. 前端生成代码

重新生成前端 TypeScript API 客户端：

bash scripts/sync-openapi-frontend.sh

生成结果:

✅ 7 个 API 文件
✅ 25 个 Model 文件
✅ 完全匹配后端 JSON 字段命名

示例生成代码:

// 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;
    // ...
}

📊 影响范围

已修改

✅ backend/docs/openapi.yaml - OpenAPI 规范
✅ frontend/src/api/generated/* - 自动生成的 TypeScript 代码

无需修改

✅ 后端 Go DTO 代码 - 保持原有 snake_case
✅ 前端手写的临时修复代码 - 现在可以使用生成的代码替换

🎯 后续工作

可选优化（前端）

前端中手写的类型定义现在可以删除，直接使用生成的代码：

需要清理的文件:

frontend/src/core/types/index.ts - 包含手写的 snake_case 类型
frontend/src/core/api/instance.api.ts - 包含手写的接口定义
frontend/src/core/api/unified-api.ts - 包含手写的接口定义

推荐做法: 直接导入并使用自动生成的类型：

import { 
  ClusterResponse, 
  CreateClusterRequest,
  InstanceResponse 
} from '@/api/generated';

✅ 验证

字段命名一致性检查

字段	后端 JSON	OpenAPI	前端生成	状态
`ca_data`	✅	✅	✅	一致
`cert_data`	✅	✅	✅	一致
`key_data`	✅	✅	✅	一致
`cluster_id`	✅	✅	✅	一致
`registry_id`	✅	✅	✅	一致
`created_at`	✅	✅	✅	一致
`updated_at`	✅	✅	✅	一致

📝 注意事项

OpenAPI 规范字段仍使用 camelCase: 如 operationId, requestBody 等元字段
业务数据字段统一 snake_case: 所有 schemas 中的属性
前端需更新代码: 如果有直接使用手写类型的地方，需要切换到生成的类型

🔗 相关文件

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

5.3 KiB Raw Blame History Unescape Escape