# 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会自动注入 ### 示例 ```java public class PropertyController { private PropertyService propertyService; // 提供setter方法即可,无需注解 public void setPropertyService(PropertyService propertyService) { this.propertyService = propertyService; } } ``` ## 参数校验 ### 手动代码校验 - 使用 `StringUtils.isBlank()` 检查字符串 - 使用 `if` 语句进行逻辑判断 - **不使用** `@Valid` 注解或 JSR303 校验 ### 示例 ```java // 必填参数校验 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方法即可 ```java // 正确 - 不需要try-catch PropertyResult result = propertyService.queryPrice(model); // 错误 - 不要这样写 // try { // PropertyResult result = propertyService.queryPrice(model); // } catch (Exception e) { // ... // } ``` ## 返回值规范 ### 统一返回格式 所有接口返回 `RestfulModelAndView` 对象: ```java RestfulModelAndView mav = new RestfulModelAndView(); ``` ### 设置返回内容 使用 `BasicModel` 构建返回对象: ```java // 成功 - 返回数据 mav.setModel(BasicModel.buildOKModel().setResult(data)); // 成功 - 无数据 mav.setModel(BasicModel.buildOKModel()); // 失败 - 参数错误 mav.setModel(BasicModel.buildBadRequestModel("错误描述")); ``` ### JSON格式 返回的JSON格式: ```json { "code": 200, "msg": "ok", "result": { // 实际数据 } } ``` ## 编码规范 | 项目 | 规范 | |-----|------| | **字符编码** | UTF-8 | | **命名风格** | 驼峰命名法(camelCase) | | **参数大小写** | 大小写敏感 | | **URL大小写** | 大小写敏感 | ## 认证授权 ### Token认证 - 所有接口方法需要添加 `@Authority(role = Role.USER)` - 调用时必须传递 `token` 参数 - Token有效期:2小时 ```java @Authority(role = Role.USER) public class PropertyController { @Authority(role = Role.USER) public Object priceQueryAction(PropertyQueryModel model) { // ... } } ``` ## 本地测试(可选) ```bash cd deliverables/fangjiaopen mvn tomcat7:run ``` 访问地址:`http://localhost:8032/{controller}/{action}?param1=value1&token=xxx` ## 构建打包 ```bash 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