Files
main/.claude/skills/fangjia-openapi-dev/references/development-standards.md
T

4.3 KiB
Raw Blame History

OpenAPI 开发规范

项目结构

Controller层

  • 位置: projects/fangjia-open/src/main/java/com/fangjia/open/controllers/
  • 命名: {业务名}Controller.java
  • 方法命名: {方法名}Action
  • URL映射: /{controller路径}/{方法名}
    • 示例: PropertyController.priceQueryAction → /property/priceQuery

Service层

  • 位置: projects/fangjia-service/src/main/java/com/fangjia/service/{业务模块}/
  • 命名:
    • 接口: {Service名}.java
    • 实现: {Service名}Impl.java
  • 结构: 必须有接口 + 实现类

Model层

  • 位置: projects/fangjia-open/src/main/java/com/fangjia/open/model/
  • 命名: {功能名}Model.java
  • 内容: 输入参数的POJO类,包含getter/setter方法

DAO层

  • 位置: projects/fangjia-dal/src/main/java/com/fangjia/dal/
  • 原则: 优先使用已有DAO,需要时再新建
  • 基类:
    • MongoDB: AbstractMongoDao
    • MySQL: AbstractSqlDao
    • JPA: AbstractJpaCompatibleDao

依赖注入规范

约定大于配置

  • 不需要使用注解(@Service, @Autowired等)
  • 不需要手动配置Spring Bean XML
  • 只需要提供setter方法,Spring会自动注入

示例

public class PropertyController {
    private PropertyService propertyService;

    // 提供setter方法即可,无需注解
    public void setPropertyService(PropertyService propertyService) {
        this.propertyService = propertyService;
    }
}

参数校验

手动代码校验

  • 使用 StringUtils.isBlank() 检查字符串
  • 使用 if 语句进行逻辑判断
  • 不使用 @Valid 注解或 JSR303 校验

示例

// 必填参数校验
if (StringUtils.isBlank(model.getCity())) {
    mav.setModel(BasicModel.buildBadRequestModel("城市不能为空"));
    return mav;
}

// 数值范围校验
if (model.getSize() != null && model.getSize() <= 0) {
    mav.setModel(BasicModel.buildBadRequestModel("面积必须大于0"));
    return mav;
}

异常处理

统一异常处理

  • 不需要手动 try-catch
  • 框架已有统一异常处理机制
  • 直接调用Service方法即可
// 正确 - 不需要try-catch
PropertyResult result = propertyService.queryPrice(model);

// 错误 - 不要这样写
// try {
//     PropertyResult result = propertyService.queryPrice(model);
// } catch (Exception e) {
//     ...
// }

返回值规范

统一返回格式

所有接口返回 RestfulModelAndView 对象:

RestfulModelAndView mav = new RestfulModelAndView();

设置返回内容

使用 BasicModel 构建返回对象:

// 成功 - 返回数据
mav.setModel(BasicModel.buildOKModel().setResult(data));

// 成功 - 无数据
mav.setModel(BasicModel.buildOKModel());

// 失败 - 参数错误
mav.setModel(BasicModel.buildBadRequestModel("错误描述"));

JSON格式

返回的JSON格式:

{
  "code": 200,
  "msg": "ok",
  "result": {
    // 实际数据
  }
}

编码规范

项目 规范
字符编码 UTF-8
命名风格 驼峰命名法(camelCase)
参数大小写 大小写敏感
URL大小写 大小写敏感

认证授权

Token认证

  • 所有接口方法需要添加 @Authority(role = Role.USER)
  • 调用时必须传递 token 参数
  • Token有效期:2小时
@Authority(role = Role.USER)
public class PropertyController {

    @Authority(role = Role.USER)
    public Object priceQueryAction(PropertyQueryModel model) {
        // ...
    }
}

本地测试(可选)

cd deliverables/fangjiaopen
mvn tomcat7:run

访问地址:http://localhost:8032/{controller}/{action}?param1=value1&token=xxx

构建打包

cd deliverables/fangjiaopen
mvn clean package -Dmaven.test.skip=true

产物位置:deliverables/fangjiaopen/target/fangjia-open.war

部署流程

  1. 构建: Maven打包生成WAR文件
  2. Docker: Jenkins Pipeline构建Docker镜像
  3. 推送: 推送到镜像仓库 192.168.0.19:9011
  4. 部署: K8S自动部署

不需要的功能

  • ❌ 不需要限流
  • ❌ 不需要缓存配置(除非特殊说明)
  • ❌ 不需要写日志(有统一日志处理)
  • ❌ 不需要手动try-catch
  • ❌ 不需要配置Spring Bean XML