项目编写规范的README文件_java readme规范-优快云博客

本文链接：https://blog.youkuaiyun.com/Tmraz/article/details/125297315

1 来源

https://www.cnblogs.com/wj-1314/p/8547763.html
https://blog.youkuaiyun.com/justlpf/article/details/120438337
https://blog.youkuaiyun.com/wohu1104/article/details/123163790

2 参考内容


# 项目名称

<!-- 写一段简短的话描述项目 -->

## 功能特性

<!-- 描述该项目的核心功能点 -->

## 软件架构(可选)

<!-- 可以描述下项目的架构 -->

## 快速开始

### 依赖检查

<!-- 描述该项目的依赖，比如依赖的包、工具或者其他任何依赖项 -->

### 构建

<!-- 描述如何构建该项目 -->

### 运行

<!-- 描述如何运行该项目 -->

## 使用指南

<!-- 描述如何使用该项目 -->

## 如何贡献

<!-- 告诉其他开发者如果给该项目贡献源码 -->

## 社区(可选)

<!-- 如果有需要可以介绍一些社区相关的内容 -->

## 关于作者

<!-- 这里写上项目作者 -->

## 谁在用(可选)

<!-- 可以列出使用本项目的其他有影响力的项目，算是给项目打个广告吧 -->

## 许可证

<!-- 这里链接上该项目的开源许可证 -->


docs
├── devel                            # 开发文档，可以提前规划好，英文版文档和中文版文档
│   ├── en-US/                       # 英文版文档，可以根据需要组织文件结构
│   └── zh-CN                        # 中文版文档，可以根据需要组织文件结构
│       └── development.md           # 开发手册，可以说明如何编译、构建、运行项目
├── guide                            # 用户文档
│   ├── en-US/                       # 英文版文档，可以根据需要组织文件结构
│   └── zh-CN                        # 中文版文档，可以根据需要组织文件结构
│       ├── api/                     # API文档
│       ├── best-practice            # 最佳实践，存放一些比较重要的实践文章
│       │   └── authorization.md
│       ├── faq                      # 常见问题
│       │   ├── iam-apiserver
│       │   └── installation
│       ├── installation             # 安装文档
│       │   └── installation.md
│       ├── introduction/            # 产品介绍文档
│       ├── operation-guide          # 操作指南，里面可以根据RESTful资源再划分为更细的子目录，用来存放系统核心/全部功能的操作手册
│       │   ├── policy.md
│       │   ├── secret.md
│       │   └── user.md
│       ├── quickstart               # 快速入门
│       │   └── quickstart.md
│       ├── README.md                # 用户文档入口文件
│       └── sdk                      # SDK文档
│           └── golang.md
└── images                           # 图片存放目录
    └── 部署架构v1.png

工程使用说明

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接口设计标准及规范

/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的修复

DEMO
===========================

###########环境依赖
node v0.10.28+
redIs ~

###########部署步骤
1. 添加系统环境变量
    export $PORTAL_VERSION="production" // production, test, dev


2. npm install  //安装node运行环境

3. gulp build   //前端编译

4. 启动两个配置(已forever为例)
    eg: forever start app-service.js
        forever start logger-service.js


###########目录结构描述
├── Readme.md                   // help
├── app                         // 应用
├── config                      // 配置
│   ├── default.json
│   ├── dev.json                // 开发环境
│   ├── experiment.json         // 实验
│   ├── index.js                // 配置控制
│   ├── local.json              // 本地
│   ├── production.json         // 生产环境
│   └── test.json               // 测试环境
├── data
├── doc                         // 文档
├── environment
├── gulpfile.js
├── locales
├── logger-service.js           // 启动日志配置
├── node_modules
├── package.json
├── app-service.js              // 启动应用配置
├── static                      // web静态资源加载
│   └── initjson
│       └── config.js         // 提供给前端的配置
├── test
├── test-service.js
└── tools



###########V1.0.0 版本内容更新
1. 新功能     aaaaaaaaa
2. 新功能     bbbbbbbbb
3. 新功能     ccccccccc
4. 新功能     ddddddddd