208 lines
5.3 KiB
Markdown
208 lines
5.3 KiB
Markdown
# 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 代码
|
||
|
||
```bash
|
||
# 从项目根目录
|
||
make openapi-gen-frontend
|
||
|
||
# 或从 frontend 目录
|
||
cd frontend
|
||
npm run openapi-gen
|
||
```
|
||
|
||
### 前端使用示例
|
||
|
||
```typescript
|
||
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`
|
||
|
||
## ✨ 优势
|
||
|
||
1. **符合标准**: 遵循 REST API 和 JSON 最佳实践
|
||
2. **类型安全**: 完整的 TypeScript 类型支持
|
||
3. **IDE 友好**: 自动补全和类型检查
|
||
4. **无性能损耗**: 无需运行时转换
|
||
5. **维护简单**: OpenAPI 驱动，自动生成
|
||
6. **前后端一致**: 统一的命名规范
|
||
|
||
## 🔍 验证
|
||
|
||
### 检查生成的类型
|
||
|
||
```bash
|
||
grep -A 5 "export interface CreateClusterRequest" \
|
||
frontend/src/api/generated-orval/api.schemas.ts
|
||
```
|
||
|
||
应该看到:
|
||
```typescript
|
||
export interface CreateClusterRequest {
|
||
caData?: string; // ✅ camelCase
|
||
certData?: string; // ✅ camelCase
|
||
keyData?: string; // ✅ camelCase
|
||
...
|
||
}
|
||
```
|
||
|
||
### 测试 API 调用
|
||
|
||
```bash
|
||
# 启动后端
|
||
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](https://orval.dev/)
|
||
- [Google JSON Style Guide](https://google.github.io/styleguide/jsoncstyleguide.xml)
|
||
|
||
## 🎉 完成状态
|
||
|
||
✅ **方案 A 已全面实施完成！**
|
||
|
||
所有代码已修改为使用 camelCase：
|
||
- ✅ 后端 Go JSON tags
|
||
- ✅ OpenAPI 规范
|
||
- ✅ 前端 TypeScript 类型
|
||
- ✅ JSON 传输格式
|
||
|
||
项目现在符合现代 REST API 最佳实践！
|
||
|