OCDP/ocdp-go

Fork 0

Files

mangomqy c5e51ed069 ocdp v1

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

5.3 KiB

Raw Blame History

camelCase Migration Summary

🎯 目标

将项目从 snake_case JSON 迁移到 camelCase JSON，符合 REST API 最佳实践和 Google JSON Style Guide。

✅ 实施方案 A：全面 camelCase

架构设计

Backend Go
├─ struct fields: PascalCase (Go 规范)
└─ json tags: camelCase → JSON: camelCase
     ↓
OpenAPI
├─ schemas: PascalCase
└─ properties: camelCase
     ↓ Orval
Frontend TypeScript
├─ interfaces: PascalCase (TS 规范)
├─ properties: camelCase (TS 规范)
└─ JSON: camelCase (REST 标准)

📝 修改清单

1. Backend Go - JSON Tags (✅ 完成)

修改所有 DTO 文件的 JSON tags 从 snake_case → camelCase：

✅ backend/internal/adapter/input/http/dto/cluster_dto.go
- ca_data → caData
- cert_data → certData
- key_data → keyData
- has_ca_data → hasCaData
- created_at → createdAt
- updated_at → updatedAt
✅ backend/internal/adapter/input/http/dto/auth_dto.go
- refresh_token → refreshToken
- access_token → accessToken
- user_id → userId
✅ backend/internal/adapter/input/http/dto/registry_dto.go
- has_password → hasPassword
- created_at → createdAt
- updated_at → updatedAt
✅ backend/internal/adapter/input/http/dto/instance_dto.go
- registry_id → registryId
- cluster_id → clusterId
- values_yaml → valuesYaml
- keep_history → keepHistory
✅ backend/internal/adapter/input/http/dto/artifact_dto.go
- registry_id → registryId
- registry_url → registryUrl
- repository_name → repositoryName
- catalog_supported → catalogSupported
- media_type → mediaType
✅ backend/internal/adapter/input/http/dto/monitoring_dto.go
- All monitoring metrics fields converted to camelCase

2. OpenAPI Specification (✅ 完成)

✅ 创建转换脚本: backend/scripts/convert-openapi-to-camelcase.cjs
✅ 转换 backend/docs/openapi.yaml 所有属性为 camelCase
✅ 备份原文件: backend/docs/openapi.yaml.backup

3. Frontend Setup (✅ 完成)

安装 Orval

✅ 添加 orval@7.3.0 到 package.json
✅ 运行 npm install

配置 Orval

✅ 创建 frontend/orval.config.ts
✅ 配置生成器指向 OpenAPI 文件
✅ 配置 Axios mutator

创建 Axios Mutator

✅ 创建 frontend/src/api/axios-mutator.ts
✅ 配置 Axios 实例和拦截器

更新脚本

✅ 修改 package.json 的 openapi-gen 脚本使用 Orval
✅ 修改 Makefile 的 openapi-gen-frontend 使用 Orval

创建文档和示例

✅ 创建 frontend/src/api/README.md
✅ 创建 frontend/src/api/example.ts
✅ 更新 frontend/src/api/index.ts

4. 工具文件 (✅ 保留备用)

✅ frontend/src/api/case-converter.ts - 保留作为工具函数
✅ frontend/scripts/post-process-openapi.cjs - 保留作为备用方案

🚀 使用方法

重新生成 API 代码

# 从项目根目录
make openapi-gen-frontend

# 或从 frontend 目录
cd frontend
npm run openapi-gen

前端使用示例

import { createCluster, setAuthToken } from '@/api';

// 设置 token
setAuthToken('your-jwt-token');

// 创建集群 - 全部使用 camelCase ✅
const cluster = await createCluster({
  name: 'my-cluster',
  host: 'https://k8s.example.com',
  caData: 'base64...',      // ✅ camelCase
  certData: 'base64...',    // ✅ camelCase
  keyData: 'base64...',     // ✅ camelCase
});

📊 变更统计

后端 Go 文件: 6 个 DTO 文件修改
JSON Tags 转换: ~50+ 字段
OpenAPI 属性: ~50+ 属性转换
新增文件: 7 个
- orval.config.ts
- axios-mutator.ts
- case-converter.ts
- api/README.md
- api/example.ts
- convert-openapi-to-camelcase.cjs
- CAMELCASE-MIGRATION.md

✨ 优势

符合标准: 遵循 REST API 和 JSON 最佳实践
类型安全: 完整的 TypeScript 类型支持
IDE 友好: 自动补全和类型检查
无性能损耗: 无需运行时转换
维护简单: OpenAPI 驱动，自动生成
前后端一致: 统一的命名规范

🔍 验证

检查生成的类型

grep -A 5 "export interface CreateClusterRequest" \
  frontend/src/api/generated-orval/api.schemas.ts

应该看到:

export interface CreateClusterRequest {
  caData?: string;        // ✅ camelCase
  certData?: string;      // ✅ camelCase
  keyData?: string;       // ✅ camelCase
  ...
}

测试 API 调用

# 启动后端
cd backend && make run-mock

# 启动前端
cd frontend && npm run dev

# 测试 API
curl -X POST http://localhost:8080/api/v1/clusters \
  -H "Content-Type: application/json" \
  -d '{"name":"test","host":"https://k8s.example.com","caData":"..."}'

📚 参考文档

frontend/src/api/README.md - API 使用文档
frontend/src/api/example.ts - 代码示例
Orval Documentation
Google JSON Style Guide

🎉 完成状态

✅ 方案 A 已全面实施完成！

所有代码已修改为使用 camelCase：

✅ 后端 Go JSON tags
✅ OpenAPI 规范
✅ 前端 TypeScript 类型
✅ JSON 传输格式

项目现在符合现代 REST API 最佳实践！

5.3 KiB Raw Blame History Unescape Escape