136 lines
4.3 KiB
Markdown
136 lines
4.3 KiB
Markdown
# 项目名称
|
||
|
||
SPDM基线化版本
|
||
|
||
## 环境要求
|
||
|
||
- JDK 1.8+
|
||
- Maven 3.5+
|
||
- Spring Boot 2.x
|
||
- (其他依赖环境)
|
||
|
||
## 快速开始
|
||
|
||
### 项目配置
|
||
|
||
本项目使用多环境配置，请根据您的运行环境选择相应的配置文件：
|
||
|
||
1. **本地开发环境** - 使用 `application-local.yml`
|
||
2. **测试环境** - 使用 `application-dev.yml`
|
||
|
||
|
||
|
||
# 项目技术规范（v1.0）
|
||
|
||
## 一、数据库设计规范
|
||
1. **字段命名规范**
|
||
- 采用小驼峰命名法（camelCase）
|
||
- 示例：`fileName varchar(255) DEFAULT NULL COMMENT '文件名称'`
|
||
- 数据库完善表注释,必须包含字段的业务含义
|
||
- id为主键，使用Long,适配CID
|
||
-
|
||
|
||
## 二、Feign接口规范
|
||
1. **代码组织**
|
||
- 所有Feign接口必须置于`com.sdm.common.feign.inter`模块下
|
||
- 按业务模块分包（如：`feign.inter.data`、`feign.inter.system`）
|
||
|
||
2. **接口定义**
|
||
- 接口命名必须以`FeignClient`作为后缀（例：`DataQueryFeignClient`）
|
||
- 禁止使用`JSONObject`作为输入/输出参数
|
||
|
||
3. **参数规范**
|
||
- 请求参数：统一置于`common-entity-req`包，按模块分包
|
||
- 响应参数：统一置于`common-entity-resp`包，按模块分包
|
||
|
||
4. **接口实现**
|
||
- feign接口在com.sdm.common.feign.impl和各模块controller实现，用于规范接口定义
|
||
|
||
## 三、外部接口调用规范
|
||
1. **代码组织**
|
||
- 所有外部调用代码必须置于`com.sdm.common.feign.impl`模块
|
||
|
||
2. **封装要求**
|
||
```java
|
||
/**
|
||
* 外部接口调用示例
|
||
*/
|
||
@Slf4j
|
||
@Component
|
||
public class ExternalApiWrapper {
|
||
|
||
|
||
public Result<ExternalData> getExternalData(RequestParam param) {
|
||
try {
|
||
// 1. 参数校验
|
||
validateParams(param);
|
||
|
||
// 2. 接口调用
|
||
Response response = externalClient.call(param);
|
||
|
||
// 3. 响应标准化校验
|
||
if (!response.isSuccess()) {
|
||
throw new BusinessException("ERR_EXTERNAL_API", response.getErrorMsg());
|
||
}
|
||
|
||
// 4. 数据转换
|
||
return convertResponse(response);
|
||
} catch (Exception e) {
|
||
// 5. 异常处理（必须记录完整堆栈）
|
||
log.error("[外部接口调用异常] 接口: {}, 参数: {}", "getExternalData", JSON.toJSONString(param), e);
|
||
```
|
||
|
||
## 四、代码质量规范
|
||
1. **方法规范**
|
||
- 单个方法长度不超过200行
|
||
- 遵循单一职责原则进行方法拆分
|
||
|
||
2. **异常处理**
|
||
- 必须捕获并记录完整异常堆栈
|
||
- 日志格式：`[业务标记] 描述信息 关键参数={} 异常上下文={}`
|
||
|
||
3. **文档要求**
|
||
- 所有公开方法必须包含Swagger注解
|
||
- 复杂逻辑需添加实现注释
|
||
```java
|
||
/**
|
||
* 根据任务ID获取详情
|
||
* @param taskId 任务ID（必须大于0）
|
||
* @throws BusinessException 当任务不存在时抛出404异常
|
||
*/
|
||
@ApiOperation(value = "任务详情查询")
|
||
@GetMapping("/task/{taskId}")
|
||
public Result<TaskVO> getTask(@PathVariable @Min(1) Long taskId) {
|
||
// 实现代码...
|
||
}
|
||
```
|
||
|
||
4.**mybatis-plus混乱，不要直接操作mapper**
|
||
- 使用MyBatis-Plus的Service层进行数据操作，避免直接在Mapper中重复写简单SQL，复杂SQL再写到Mapper
|
||
- 禁止直接在sql操作跨微服务的表
|
||
|
||
5.**controller层返回值指定具体类型，禁止直接用JSONObject**
|
||
|
||
|
||
# 五、Git分支规范
|
||
## 一、核心原因
|
||
1. **隔离风险**：`main`分支保留稳定版本（如190环境），开发改动在独立分支进行，避免影响线上/预发布环境；
|
||
2. **清晰可控**：不同类型分支对应不同开发场景，便于追溯、协作和问题回滚；
|
||
3. **高效协作**：多人开发时避免代码冲突，功能未完成前不污染集成分支。
|
||
|
||
## 二、分支命名规范
|
||
| 分支类型 | 命名格式 | 用途 |
|
||
|----------------|-------------------------|--------------------------|
|
||
| 稳定分支 | `main` | 生产/预发布环境稳定版本 |
|
||
| 开发集成分支 | `develop` | 日常开发功能集成 |
|
||
| 新功能分支 | `feature/功能名` | 开发新需求（如feature/支付模块） |
|
||
| 开发bug修复 | `bugfix/问题描述` | 修复开发中bug（如bugfix/登录失败） |
|
||
| 线上紧急修复 | `hotfix/问题描述` | 修复线上/预发布紧急问题（如hotfix/190接口报错） |
|
||
|
||
### 总结
|
||
核心是用`main`保稳定、`develop`做集成，短期分支（feature/bugfix/hotfix）做具体开发，既保障环境稳定，又让开发流程清晰可追溯。
|
||
|
||
|
||
|
||
|