/**
* 外部接口调用示例
*/
@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);

四、代码质量规范

方法规范

单个方法长度不超过200行
遵循单一职责原则进行方法拆分

异常处理

必须捕获并记录完整异常堆栈
日志格式：[业务标记] 描述信息关键参数={} 异常上下文={}

文档要求

所有公开方法必须包含Swagger注解
复杂逻辑需添加实现注释

/**
* 根据任务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分支规范

一、核心原因

隔离风险：main分支保留稳定版本（如190环境），开发改动在独立分支进行，避免影响线上/预发布环境；
清晰可控：不同类型分支对应不同开发场景，便于追溯、协作和问题回滚；
高效协作：多人开发时避免代码冲突，功能未完成前不污染集成分支。

二、分支命名规范

分支类型	命名格式	用途
稳定分支	`main`	生产/预发布环境稳定版本
开发集成分支	`develop`	日常开发功能集成
新功能分支	`feature/功能名`	开发新需求（如feature/支付模块）
开发bug修复	`bugfix/问题描述`	修复开发中bug（如bugfix/登录失败）
线上紧急修复	`hotfix/问题描述`	修复线上/预发布紧急问题（如hotfix/190接口报错）

总结

核心是用main保稳定、develop做集成，短期分支（feature/bugfix/hotfix）做具体开发，既保障环境稳定，又让开发流程清晰可追溯。

README.md Unescape Escape

项目名称

环境要求

快速开始

项目配置

项目技术规范（v1.0）

一、数据库设计规范

二、Feign接口规范

三、外部接口调用规范

四、代码质量规范

五、Git分支规范

一、核心原因

二、分支命名规范

总结

README.md