Update project_rules.md (#2083)
This commit is contained in:
Qing Liang
GitHub
@@ -189,13 +189,24 @@ web/
|
||||
#### **1. 模型层 (`model/`)**
|
||||
|
||||
- **数据模型 (`model/xxx.go`)**:
|
||||
|
||||
- 用于定义与数据库表映射的 GORM 结构体。
|
||||
|
||||
- 结构体应继承 `global.GVA_MODEL` 以包含 `ID`, `CreatedAt`, `UpdatedAt` 等基础字段。
|
||||
|
||||
- 必须为字段添加清晰的 `json` 和 `gorm` 标签。
|
||||
|
||||
|
||||
- 用于定义与数据库表映射的 GORM 结构体。
|
||||
|
||||
- 结构体应继承 `global.GVA_MODEL` 以包含 `ID`, `CreatedAt`, `UpdatedAt` 等基础字段。
|
||||
|
||||
- 必须为字段添加清晰的 `json` 和 `gorm` 标签。
|
||||
|
||||
- **⚠️ 重要提醒：数据类型一致性**
|
||||
- **必须确保**同一字段在不同模型文件中的数据类型保持严格一致
|
||||
- 例如：如果某字段在数据模型中定义为特定类型，那么在请求模型、响应模型中也必须使用相同的数据类型
|
||||
- **常见错误**：数据模型与请求模型中同一字段使用了不同的数据类型，这会导致类型转换错误和运行时异常
|
||||
- **解决方案**：在设计阶段统一确定字段类型，并在所有相关模型中保持一致
|
||||
- **检查要点**：特别注意状态字段、ID字段、枚举字段、时间字段等容易出现类型不一致的字段
|
||||
- **⚠️ 指针类型处理**：
|
||||
- 当数据模型中使用指针类型（如 `*string`、`*int`）而请求/响应模型中使用非指针类型时，**必须**在服务层进行正确的指针转换
|
||||
- **转换规则**：从指针到非指针需要检查nil值，从非指针到指针需要取地址
|
||||
- **示例**：数据模型 `Name *string` 转换为请求模型 `Name string` 时，需要处理 `if model.Name != nil { request.Name = *model.Name }`
|
||||
|
||||
- **请求模型 (`model/request/xxx.go`)**:
|
||||
|
||||
- 用于定义接收前端请求参数的结构体（DTOs）。
|
||||
@@ -212,7 +223,12 @@ web/
|
||||
- **结构**: 在 `service/` 下为每个模块创建 `xxx_service.go` 文件，并在 `service/enter.go` 中注册。
|
||||
|
||||
- **函数签名**: 函数应接收具体的业务参数（如 `model.Xxx` 或 `request.XxxSearch`），并返回处理结果和 `error`。
|
||||
|
||||
|
||||
- **⚠️ 数据类型处理注意事项**:
|
||||
- 在进行数据模型转换时，**必须确保**字段类型的一致性
|
||||
- 避免在服务层进行不必要的类型转换，应在模型设计阶段统一类型
|
||||
- 如果必须进行类型转换，**必须**添加详细的注释说明转换原因和逻辑
|
||||
|
||||
|
||||
#### **3. API层 (`api/`)**
|
||||
|
||||
@@ -608,6 +624,12 @@ src/plugin/[插件名]/
|
||||
- **统一**响应格式：`{code, data, msg}`
|
||||
- **统一**分页格式：`{page, pageSize, total, list}`
|
||||
- **统一**时间格式：ISO 8601标准
|
||||
- **⚠️ 数据类型一致性**：
|
||||
- 前后端对于同一字段**必须**使用相同的数据类型
|
||||
- 后端Go结构体中的字段类型必须与前端JavaScript/TypeScript中的类型定义保持一致
|
||||
- 特别注意：状态字段、ID字段、枚举值、时间字段等容易出现类型不匹配的字段
|
||||
- 示例：后端数值类型字段对应前端 `number` 类型，字符串类型对应 `string` 类型，布尔类型对应 `boolean` 类型
|
||||
- **指针类型处理**：后端Go中的指针类型在JSON序列化时会自动处理nil值，前端接收到的是对应的基础类型或null值
|
||||
|
||||
3. **错误处理**:
|
||||
- 后端**必须**返回标准化的错误码和错误信息
|
||||
@@ -719,10 +741,11 @@ web/src/plugin/[插件名]/
|
||||
|
||||
1. **功能完整性**: 插件功能完整，满足业务需求
|
||||
2. **代码质量**: 代码规范，注释完整，易于维护
|
||||
3. **性能表现**: 响应速度快，资源占用合理
|
||||
4. **用户体验**: 界面友好，操作流畅，错误处理完善
|
||||
5. **兼容性**: 与主系统兼容，不影响其他功能
|
||||
6. **安全性**: 数据安全，权限控制，防止安全漏洞
|
||||
3. **数据类型一致性**: 前后端数据模型字段类型保持严格一致，避免类型转换错误
|
||||
4. **性能表现**: 响应速度快，资源占用合理
|
||||
5. **用户体验**: 界面友好，操作流畅，错误处理完善
|
||||
6. **兼容性**: 与主系统兼容，不影响其他功能
|
||||
7. **安全性**: 数据安全，权限控制，防止安全漏洞
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -195,7 +195,18 @@ web/
|
||||
- 结构体应继承 `global.GVA_MODEL` 以包含 `ID`, `CreatedAt`, `UpdatedAt` 等基础字段。
|
||||
|
||||
- 必须为字段添加清晰的 `json` 和 `gorm` 标签。
|
||||
|
||||
|
||||
- **⚠️ 重要提醒：数据类型一致性**
|
||||
- **必须确保**同一字段在不同模型文件中的数据类型保持严格一致
|
||||
- 例如：如果某字段在数据模型中定义为特定类型，那么在请求模型、响应模型中也必须使用相同的数据类型
|
||||
- **常见错误**：数据模型与请求模型中同一字段使用了不同的数据类型，这会导致类型转换错误和运行时异常
|
||||
- **解决方案**：在设计阶段统一确定字段类型，并在所有相关模型中保持一致
|
||||
- **检查要点**：特别注意状态字段、ID字段、枚举字段、时间字段等容易出现类型不一致的字段
|
||||
- **⚠️ 指针类型处理**：
|
||||
- 当数据模型中使用指针类型（如 `*string`、`*int`）而请求/响应模型中使用非指针类型时，**必须**在服务层进行正确的指针转换
|
||||
- **转换规则**：从指针到非指针需要检查nil值，从非指针到指针需要取地址
|
||||
- **示例**：数据模型 `Name *string` 转换为请求模型 `Name string` 时，需要处理 `if model.Name != nil { request.Name = *model.Name }`
|
||||
|
||||
- **请求模型 (`model/request/xxx.go`)**:
|
||||
|
||||
- 用于定义接收前端请求参数的结构体（DTOs）。
|
||||
@@ -212,7 +223,12 @@ web/
|
||||
- **结构**: 在 `service/` 下为每个模块创建 `xxx_service.go` 文件，并在 `service/enter.go` 中注册。
|
||||
|
||||
- **函数签名**: 函数应接收具体的业务参数（如 `model.Xxx` 或 `request.XxxSearch`），并返回处理结果和 `error`。
|
||||
|
||||
|
||||
- **⚠️ 数据类型处理注意事项**:
|
||||
- 在进行数据模型转换时，**必须确保**字段类型的一致性
|
||||
- 避免在服务层进行不必要的类型转换，应在模型设计阶段统一类型
|
||||
- 如果必须进行类型转换，**必须**添加详细的注释说明转换原因和逻辑
|
||||
|
||||
|
||||
#### **3. API层 (`api/`)**
|
||||
|
||||
@@ -604,10 +620,16 @@ src/plugin/[插件名]/
|
||||
- 接口变更**必须**提前通知并更新文档
|
||||
|
||||
2. **数据格式**:
|
||||
- **统一**使用JSON格式进行数据交换
|
||||
- **统一**响应格式：`{code, data, msg}`
|
||||
- **统一**分页格式：`{page, pageSize, total, list}`
|
||||
- **统一**时间格式：ISO 8601标准
|
||||
- **统一**使用JSON格式进行数据交换
|
||||
- **统一**响应格式：`{code, data, msg}`
|
||||
- **统一**分页格式：`{page, pageSize, total, list}`
|
||||
- **统一**时间格式：ISO 8601标准
|
||||
- **⚠️ 数据类型一致性**：
|
||||
- 前后端对于同一字段**必须**使用相同的数据类型
|
||||
- 后端Go结构体中的字段类型必须与前端JavaScript/TypeScript中的类型定义保持一致
|
||||
- 特别注意：状态字段、ID字段、枚举值、时间字段等容易出现类型不匹配的字段
|
||||
- 示例：后端数值类型字段对应前端 `number` 类型，字符串类型对应 `string` 类型，布尔类型对应 `boolean` 类型
|
||||
- **指针类型处理**：后端Go中的指针类型在JSON序列化时会自动处理nil值，前端接收到的是对应的基础类型或null值
|
||||
|
||||
3. **错误处理**:
|
||||
- 后端**必须**返回标准化的错误码和错误信息
|
||||
@@ -719,10 +741,11 @@ web/src/plugin/[插件名]/
|
||||
|
||||
1. **功能完整性**: 插件功能完整，满足业务需求
|
||||
2. **代码质量**: 代码规范，注释完整，易于维护
|
||||
3. **性能表现**: 响应速度快，资源占用合理
|
||||
4. **用户体验**: 界面友好，操作流畅，错误处理完善
|
||||
5. **兼容性**: 与主系统兼容，不影响其他功能
|
||||
6. **安全性**: 数据安全，权限控制，防止安全漏洞
|
||||
3. **数据类型一致性**: 前后端数据模型字段类型保持严格一致，避免类型转换错误
|
||||
4. **性能表现**: 响应速度快，资源占用合理
|
||||
5. **用户体验**: 界面友好，操作流畅，错误处理完善
|
||||
6. **兼容性**: 与主系统兼容，不影响其他功能
|
||||
7. **安全性**: 数据安全，权限控制，防止安全漏洞
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -195,7 +195,18 @@ web/
|
||||
- 结构体应继承 `global.GVA_MODEL` 以包含 `ID`, `CreatedAt`, `UpdatedAt` 等基础字段。
|
||||
|
||||
- 必须为字段添加清晰的 `json` 和 `gorm` 标签。
|
||||
|
||||
|
||||
- **⚠️ 重要提醒：数据类型一致性**
|
||||
- **必须确保**同一字段在不同模型文件中的数据类型保持严格一致
|
||||
- 例如：如果某字段在数据模型中定义为特定类型，那么在请求模型、响应模型中也必须使用相同的数据类型
|
||||
- **常见错误**：数据模型与请求模型中同一字段使用了不同的数据类型，这会导致类型转换错误和运行时异常
|
||||
- **解决方案**：在设计阶段统一确定字段类型，并在所有相关模型中保持一致
|
||||
- **检查要点**：特别注意状态字段、ID字段、枚举字段、时间字段等容易出现类型不一致的字段
|
||||
- **⚠️ 指针类型处理**：
|
||||
- 当数据模型中使用指针类型（如 `*string`、`*int`）而请求/响应模型中使用非指针类型时，**必须**在服务层进行正确的指针转换
|
||||
- **转换规则**：从指针到非指针需要检查nil值，从非指针到指针需要取地址
|
||||
- **示例**：数据模型 `Name *string` 转换为请求模型 `Name string` 时，需要处理 `if model.Name != nil { request.Name = *model.Name }`
|
||||
|
||||
- **请求模型 (`model/request/xxx.go`)**:
|
||||
|
||||
- 用于定义接收前端请求参数的结构体（DTOs）。
|
||||
@@ -212,7 +223,12 @@ web/
|
||||
- **结构**: 在 `service/` 下为每个模块创建 `xxx_service.go` 文件，并在 `service/enter.go` 中注册。
|
||||
|
||||
- **函数签名**: 函数应接收具体的业务参数（如 `model.Xxx` 或 `request.XxxSearch`），并返回处理结果和 `error`。
|
||||
|
||||
|
||||
- **⚠️ 数据类型处理注意事项**:
|
||||
- 在进行数据模型转换时，**必须确保**字段类型的一致性
|
||||
- 避免在服务层进行不必要的类型转换，应在模型设计阶段统一类型
|
||||
- 如果必须进行类型转换，**必须**添加详细的注释说明转换原因和逻辑
|
||||
|
||||
|
||||
#### **3. API层 (`api/`)**
|
||||
|
||||
@@ -604,10 +620,16 @@ src/plugin/[插件名]/
|
||||
- 接口变更**必须**提前通知并更新文档
|
||||
|
||||
2. **数据格式**:
|
||||
- **统一**使用JSON格式进行数据交换
|
||||
- **统一**响应格式：`{code, data, msg}`
|
||||
- **统一**分页格式：`{page, pageSize, total, list}`
|
||||
- **统一**时间格式：ISO 8601标准
|
||||
- **统一**使用JSON格式进行数据交换
|
||||
- **统一**响应格式：`{code, data, msg}`
|
||||
- **统一**分页格式：`{page, pageSize, total, list}`
|
||||
- **统一**时间格式：ISO 8601标准
|
||||
- **⚠️ 数据类型一致性**：
|
||||
- 前后端对于同一字段**必须**使用相同的数据类型
|
||||
- 后端Go结构体中的字段类型必须与前端JavaScript/TypeScript中的类型定义保持一致
|
||||
- 特别注意：状态字段、ID字段、枚举值、时间字段等容易出现类型不匹配的字段
|
||||
- 示例：后端数值类型字段对应前端 `number` 类型，字符串类型对应 `string` 类型，布尔类型对应 `boolean` 类型
|
||||
- **指针类型处理**：后端Go中的指针类型在JSON序列化时会自动处理nil值，前端接收到的是对应的基础类型或null值
|
||||
|
||||
3. **错误处理**:
|
||||
- 后端**必须**返回标准化的错误码和错误信息
|
||||
@@ -719,10 +741,11 @@ web/src/plugin/[插件名]/
|
||||
|
||||
1. **功能完整性**: 插件功能完整，满足业务需求
|
||||
2. **代码质量**: 代码规范，注释完整，易于维护
|
||||
3. **性能表现**: 响应速度快，资源占用合理
|
||||
4. **用户体验**: 界面友好，操作流畅，错误处理完善
|
||||
5. **兼容性**: 与主系统兼容，不影响其他功能
|
||||
6. **安全性**: 数据安全，权限控制，防止安全漏洞
|
||||
3. **数据类型一致性**: 前后端数据模型字段类型保持严格一致，避免类型转换错误
|
||||
4. **性能表现**: 响应速度快，资源占用合理
|
||||
5. **用户体验**: 界面友好，操作流畅，错误处理完善
|
||||
6. **兼容性**: 与主系统兼容，不影响其他功能
|
||||
7. **安全性**: 数据安全，权限控制，防止安全漏洞
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user