# springboot-web-demo **Repository Path**: terrywangxp/springboot-web-demo ## Basic Information - **Project Name**: springboot-web-demo - **Description**: Web工程Demo - **Primary Language**: Java - **License**: MulanPSL-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 2 - **Created**: 2021-06-18 - **Last Updated**: 2021-07-06 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 开发规范 ## package规范 【强制】包名统一使用小写。包名统一使用单数形式，格式："com.sinitek.产品名称.模块名称(+).功能"。例如：com.sinitek.sirm.common，或者 com.sinitek.aim.product 包名中的“功能”(“功能”是不可以再有下级 package)，约定如下： | 功能 | 说明 | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | frontend | 前后端分离后未整理之前的控制器（Controller），类名以 ApiAction 为结尾，如果项目是纯前后端分离的，后端部分的 Controller 类可以写到 controller 下 | | controller | 控制器，类名以 Controller 为结尾，模块名作为前缀，例如 InvestController | | entity | 实体。按数据库表命名，大驼峰，例如数据库表 DEMO_INVEST，对应的实体是 DemoInvest | | service | 服务接口类，以 I 开头，以 Service 为结尾 | | mapper | DB 接口类，以 Mapper 为结尾。资源名作为前缀，一个 Mapper 尽量只操作一个资源，例如 DemoInvestMapper | | vo | 前后端交互的展示对象，类名以 VO 为结尾 | | dto | 数据传输对象，类名以 DTO 为结尾 | | util | 工具类，类名以 Util 为结尾 | | support | 模型 | | constant | 常量。命名规范：[模块][分类]Constant，例如 DemoInvestConstant；当某一类常量较多时可以在模块名后增加分类，例如 DemoInvestErrorCodeConstant | | config | SpringBoot 配置类(@Configuration),以Config或Configuration结尾 | | exception | 异常，类名以 Exception 为结尾 | | enumerate | 枚举类。 | | feign | Spring Cloud Feign 接口类,远调其他服务,类名以 Feign 结尾 | | job | 定时任务类,类名以 Job 结尾 | | serlvet | 类名以 Servlet 结尾 | | filter | 类名以 Filter 结尾 | | interceptor | 拦截器，类名以 Interceptor 结尾 | | webservice | webService，类名以 WebService 结尾 | | annotation | 注解 | | event | 事件。类名以Event为结尾 | | event/publisher | 事件手工发布者。类名以EventPublisher为结尾　 | | event/listener | 事件监听处理器。类名以EventListener为结尾　 | ## 后端URL规范 规则目的：为了能够根据 url 快速的找到相应的 Java 类和方法。 1. 后端接口的 URL 按如下规则进行编制： /frontend/api/ [ 通用分类 ] / [ 模块...... ] /.../ [ 功能 ] **通用分类** | - | - | | --- | ----------------------- | | dwr | 用于模拟 dwr 组件的功能 | | api | 表示应用数据接口 | | api/remote | 表示接口对外提供服务 | 2. URI 表示的是特定的资源，使用小写的单数名词来表示，多个单词之间用‘-’分割；为了寻找方面 URI 中的每一段和 package 目录保持一致。 3. 数据接口的请求类型使用“GET（查看）、POST（新建/编辑／删除）”。 （注：尽量使用 POST） 4. URL 和 Controller 的对应关系。绝大多情况下 URL 表示对资源的操作，【功能】表示在“Controller”下的方法，【功能】取名规则：“<动词>\[-资源\]”，在 Java 中的方法名按照驼峰命名法命名，“\[资源\]非必填”，例如： | 功能 | 路径 | 请求类型 | Controller | 方法 | | ------------ | ------------------------ | -------- | ------------------------- | ------ | | 获取用户 | /org/user/list | GET | OrgUserController | list | | 查看合同信息 | /project/contract/view | GET | ProjectContractController | view | | 保存合同信息 | /project/contract/save | POST | ProjectContractController | save | | 提交合同信息 | /project/contract/submit | POST | ProjectContractController | submit | | 删除合同信息 | /project/contract/delete | POST | ProjectContractController | delete | 常用动词： | 常用动词 | 说明 | | -------- | ---------------------------- | | list | 查询 | | draft | 保存草稿。记录未生效 | | save | 确定。无需流程，数据已生效。 | | submit | 提交，发起流程 | | delete | 删除 | | detail | 详细 | | load | 加载 | ## API接口规范 ### Api Api 标记可以标记一个 Controller 类做为 swagger 文档资源，使用方式： ```java @Api(value = "URI地址", tags = "命名规范:[模块分类:多个模块之间使用'-'分隔']/[资源名称-中文]接口") @Controller public class AbcController{ } ``` 示例： ```java @RequestMapping("/frontend/api/demo/invest") @Api(value="/frontend/api/demo/invest", tags="Demo-投资信息接口") @Controller public class DemoInvestController { } ``` 属性配置： | 属性名称 | 是否必填 | 备注 | | -------------- | -------- | ---------------------------------------------------------- | | value | 必填 | url 的路径值 | | tags | 必填 | 如果设置这个值、value 的值会被覆盖 | | description | | 对 api 资源的描述 | | basePath | | 基本路径可以不配置 | | position | | 如果配置多个 Api 想改变显示的顺序位置 | | consumes | | 请求提交内容类型,例如: "application/json, application/xml" | | protocols | | 使用的协议,例如: http, https, ws, wss. | | authorizations | | 高级特性认证时配置 | | hidden | | 配置为 true 将在文档中隐藏 | ### ApiOperation ApiOperation 每一个 url 资源的定义,使用方式： ```java @GetMapping("/list") @ApiOperation("操作描述，中文") public 返回值 listInvest() { } ``` 属性配置： | 属性名称 | 是否必填 | 备注 | | ----------------- | -------- | ------------------------------------------------------------- | | value | 必填 | url 的路径值 | | tags | | 如果设置这个值、value 的值会被覆盖 | | description | | 对 api 资源的描述 | | basePath | | 基本路径可以不配置 | | position | | 如果配置多个 Api 想改变显示的顺序位置 | | produces | | 返回值类型,例如: "application/json, application/xml" | | consumes | | 请求提交内容类型,例如: "application/json, application/xml" | | protocols | | 使用的协议,例如: http, https, ws, wss. | | authorizations | | 高级特性认证时配置 | | hidden | | 配置为 true 将在文档中隐藏 | | response | | 返回的对象 | | responseContainer | | 这些对象是有效的 "List", "Set" or "Map".，其他无效 | | httpMethod | | "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH" | | code | | http 的状态码 默认 200 | | extensions | | 扩展属性 | Demo: ```java @PostMapping("/load") @ApiOperation("加载投资信息") public RequestResult loadInvest(@RequestBody @ApiParam LoadInvestDTO loadInvestDTO){ ... } ``` ### ApiParam ApiParam 请求属性,使用方式： ```java // 如果参数是基本数据类型，那么ApiParam中需要添加“属性名称”（中文） @PostMapping("/delete") @ApiOperation("删除投资信息") public RequestResult deleteInvest(@RequestBody @ApiParam("记录id集合") Long[] ids){ ... } // 如果参数是一个对象，那么ApiParam中可以不添加“属性名称” @PostMapping("/load") @ApiOperation("加载投资信息") public RequestResult loadInvest(@RequestBody @ApiParam LoadInvestDTO loadInvestDTO){ ... } ``` 属性配置： | 属性名称 | 备注 | | --------------- | ------------ | | name | 属性名称 | | value | 属性值 | | defaultValue | 默认属性值 | | allowableValues | 可以不配置 | | required | 是否属性必填 | | allowMultiple | 默认为 false | | hidden | 隐藏该属性 | | example | 举例子 | ### ApiModel ApiModel 标记一个实体做为文档资源，如请求对象 ```java @Data @ApiModel("数据对象名称，中文") public class UserAddRequest {} ``` Demo: ```java @Data @ApiModel("重新修订放弃信息") public class GiveupInvestDTO {} ``` ### ApiModelProperty ApiModelProperty 标记属性 Demo: ```java @ApiModel(description = "重新修订放弃信息") public class GiveupInvestDTO { @ApiModelProperty(value = "流程审批人Id", required = true) private Long exampleOwnerId; // 如果只有value属性，那么可以简写成如下形式 @ApiModelProperty("流程实例id") private Long exampleId; } ``` ### API文档路径 /swagger-ui.html ## 文档规范 [文档规范](doc/doc_spec.md)