4.3 KiB
4.3 KiB
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
- MongoDB:
依赖注入规范
约定大于配置
- 不需要使用注解(@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
部署流程
- 构建: Maven打包生成WAR文件
- Docker: Jenkins Pipeline构建Docker镜像
- 推送: 推送到镜像仓库
192.168.0.19:9011 - 部署: K8S自动部署
不需要的功能
- ❌ 不需要限流
- ❌ 不需要缓存配置(除非特殊说明)
- ❌ 不需要写日志(有统一日志处理)
- ❌ 不需要手动try-catch
- ❌ 不需要配置Spring Bean XML