工程README.md文件样式及软件版本号说明

分手后的思念是犯贱 2022-08-28 12:50 241阅读 0赞

# 1.版本号维护 #

> 如：1.0.0  
> 主版本号.次版本号.增强版本号.里程碑版本号  
> 主版本号：项目的重大重构  
> 次版本号：新功能的添加和变化  
> 增强版本号：BUG的修复

# 2.README.md示例  #

## 工程使用说明     
    
    ### 1.代码结构
    ````
    foundation-web
        - java
            - user
                - controller
                - dao
                - mapper
                - exception
                - param
                - entity
                - service
                    - impl
                - validation
            - menu
                ...
            - config
        - resources
            - ddl 
            - dml
            - sql
            - i18n
            - application.yml
            - logback-spring.xml
            
    ````
    ### 2.RESTful API接口设计标准及规范
    * URI
    ````
    /api/v1/user-roles
    api开头，后面跟版本号
    资源一般对应领域模型中的实体类
    URI中的名词表示资源集合，使用复数形式
    不用大写
    用中杠-
    层级最多两级，/api/v1/groups/1/teams/1/users -> /api/v1/users?groups=1&teams=1
    ````
    * Request
    ````
    通过标准HTTP Method对资源CRUD
    GET：查询
    POST：创建单个资源
    PUT：更新单个资源（全量），客户端提供完整的更新后的资源
    PATCH：负责部分更新，客户端提供要更新的那些字段
    DELETE：删除
    
    1.分页使用PageParam接收参数，对于URL相同，参数不同的查询，可通过GetMapping的params参数进行区分
    2.查询全部使用GetMapping
    3.单个字段的更新 PATCH /user/1/address
    ````
    ### 3.返回值规范
    ````
    1.对于成功的响应（200），直接返回结果，不要封装成ResultBean之类的结构
    2.对于失败的响应（404，401，403，500等），抛出异常，在GlobalExceptionHandler统一处理，返回cn.bba.boot.starter.web.dto.ErrorDTO
    ````
    ### 4.参数校验
    ````
    使用注解进行参数校验，不允许硬编码方式的校验
    Controller方法参数使用@Validated，可以分组校验
    级联校验时，属性上使用@Valid
    对于平铺方式的参数直接使用@Max、@Min等注解
    ````
    ### 4.权限校验
    ````
    pom中引入bba-boot-starter-security
    1.url权限
    使用@ApiAuthority进行校验
        authority：权限的code
        name：权限的名称
        description：权限的描述
    在Controller中添加注释之后，调用POST /api/v1/permissions/sync，所有@ApiAuthority中定义了的权限同步到数据库中
    2.数据权限
    使用@DataAuthority进行校验
        key：通过spel表达式定位参数
        processor：实现DataAuthorityProcessor,编写自己的处理器
    ````
    ### 5.版本号维护
    ````
    如：1.0.0
    主版本号.次版本号.增强版本号.里程碑版本号
    主版本号：项目的重大重构
    次版本号：新功能的添加和变化
    增强版本号：BUG的修复
    ````