Merge pull request #51 from carrypann/develop

docs: 补全文档 #46

Author: carrypann

README.md

@@ -11,8 +11,11 @@
 - 提供gradle快速发布插件[devops-publish-gradle-plugin](./devops-boot-project/devops-boot-tools/devops-publish-gradle-plugin/README.md)
 - 提供统一版本依赖管理[devops-boot-dependencies](./devops-boot-project/devops-boot-dependencies/README.md)
 - 提供多个开箱即用的starter组件
-  - [logging日志组件](./devops-boot-project/devops-boot-starters/devops-boot-starter-logging/README.md)
-  - TODO
+  - [starter-logging](./devops-boot-project/devops-boot-starters/devops-boot-starter-logging/README.md)
+  - [starter-api](./devops-boot-project/devops-boot-starters/devops-boot-starter-api/README.md)
+  - [starter-web](./devops-boot-project/devops-boot-starters/devops-boot-starter-web/README.md)
+  - [starter-service](./devops-boot-project/devops-boot-starters/devops-boot-starter-service/README.md)
+  - TODO  
 
 ## 快速开始
 - **gradle.build.kts**
@@ -59,4 +62,3 @@ devops-framework/
 ## 发行版本
 - 0.0.1 2020年10月9日
 - 0.0.2 2020年12月22日
-

devops-boot-project/devops-boot-core/devops-service/build.gradle.kts

@@ -2,7 +2,6 @@ description = "DevOps Boot Service"
 
 dependencies {
     api(project(":devops-boot-project:devops-boot-core:devops-web"))
-    api("org.springframework.boot:spring-boot-starter-actuator")
     api("com.squareup.okhttp3:okhttp")
     api("io.github.openfeign:feign-okhttp")
     api("org.springframework.cloud:spring-cloud-starter-openfeign")

devops-boot-project/devops-boot-dependencies/README.md

@@ -31,6 +31,9 @@ dependencyManagement {
 }
 ```
 
+## 依赖版本列表
+请参考[build.gradle.kts](./build.gradle.kts)的`constraints`列表
+
 ### 参考
 关于依赖管理的使用详情，请参考官方文档[dependency-management](https://docs.spring.io/dependency-management-plugin/docs/current/reference/html/)
 

devops-boot-project/devops-boot-starters/devops-boot-starter-api/README.md

@@ -0,0 +1,36 @@
+# devops-boot-starter-api
+
+`starter-api`组件用于帮助开发者完成api接口的编写
+
+## 功能介绍
+- 规范统一的接口协议并定义统一的`POJO`类
+- 自动引入`swagger`注解需要的相关jar包
+- 提供`HTTP`相关的常用常量和枚举类
+
+## 使用方式
+- **build.gradle.kts**
+
+```kotlin
+implementation("com.tencent.devops:devops-boot-starter-api")
+```
+
+- **build.gradle**
+
+```groovy
+implementation 'com.tencent.devops:devops-boot-starter-api'
+```
+
+## 最佳实践
+
+项目的`api`模块包含了对外接口的声明以及数据格式的定义，最终作为二方包或者三方包提供给对外使用，因此需要开发者保持`api`模块的精简和规范，否则会引诸多问题，如：
+1. 不规范的依赖声明方式导致版本依赖冲突
+2. 引入过多/多余的依赖，导致臃肿
+3. 在`api`模块中暴露敏感信息，如`DO`类
+
+`starter-api`组件秉承这一理念，帮助开发者最大化精简和规范`api`模块的开发，但开发者仍然需要注意以下事项：
+1. `api`模块慎重引入依赖，如需引入请考楼`implementation`或`comipleOnly`方式
+2. 对于`@RequestMapping`、`@FeignClient`注解的依赖，使用`comipleOnly`的方式依赖
+    ```kotlin
+      compileOnly("org.springframework.cloud:spring-cloud-openfeign-core")
+    ```
+3. `api`模块保持简洁，只包含和接口声明和数据格式的定义

devops-boot-project/devops-boot-starters/devops-boot-starter-logging/README.md

@@ -1,15 +1,16 @@
 # devops-boot-starter-logging
 
-logging组件帮助开发者完成日志的快速配置，并统一日志风格。
+logging组件帮助开发者完成日志的快速配置，并统一日志格式。
 
 ## 功能介绍
  - 基于`slf4j`+`logback`
  - 提供`logback`基础配置文件，支持`include`方式引入
    - `base.xml` 基础属性配置
    - `appender.xml` `appender`配置
  - 配置统一的日志打印格式
- - 配置统一的日志输出为HI
+ - 配置统一的日志输出位置
  - 配置统一的日志切割策略
+ - 配置统一的异步日志输出
  - 约定统一的日志分类方式
    - 访问日志: {application}-access.log
    - 应用日志: {application}-app.log
@@ -32,4 +33,14 @@ implementation 'com.tencent.devops:devops-boot-starter-logging'
 
 | 属性               | 类型    | 默认值 | 说明               |
 | ------------------ | ------- | ------ | ------------------ |
-| logging.file.path  | string | ./  | 日志输出位置，默认当前目录 |
+| logging.file.path  | string | ./  | 日志输出位置，默认当前目录 |
+| logging.level.\<loggerName\> | string | INFO | 调整`loggerName`日志级别, `root`代表所有logger |
+
+## 说明
+
+logging组件会自动根据不同的`profile`应用不同的appender配置
+
+| profile                   | 初始日志级别 | appender           |
+| ------------------------- | ----------- | ----------------- |
+| `default`、`local`、`dev`  | INFO        | `console`、`file` |
+| `test`、`prod`             | INFO        | `file`            |

devops-boot-project/devops-boot-starters/devops-boot-starter-service/README.md

@@ -0,0 +1,31 @@
+# devops-boot-starter-service
+
+`starter-service`组件帮助开发者完成与微服务相关的快速配置
+
+## 功能介绍
+- 引入`spring-cloud-starter-openfeign`
+- 引入`spring-cloud-starter-consul-discovery`
+- 引入`spring-cloud-starter-consul-config`
+- 引入`spring-cloud-starter-netflix-hystrix`
+- 引入`okhttp`并配置feign底层使用`OkHttpClient`
+- 配置`hystrix`和`ribbon`
+- 引入`jackson`并完成序列化和反序列化的配置
+- 配置自定义`RequestMappingHandlerMapping`解决`SpringMVC`注解重复扫描问题
+
+
+## 使用方式
+- **build.gradle.kts**
+
+```kotlin
+implementation("com.tencent.devops:devops-boot-starter-service")
+```
+
+- **build.gradle**
+
+```groovy
+implementation 'com.tencent.devops:devops-boot-starter-service'
+```
+
+## 模块依赖
+`starter-serivce`添加了如下依赖，对于这些模块的依赖不需要重复声明:
+- `com.tencent.devops:devops-boot-starter-web`

devops-boot-project/devops-boot-starters/devops-boot-starter-web/README.md

@@ -0,0 +1,42 @@
+# devops-boot-starter-web
+
+`starter-web`组件帮助开发者完成与web相关的快速配置
+
+## 功能介绍
+- 引入`undertow`
+- 引入`spring-boot`的`actuator`组件
+- 引入`springfox-starter`并完成`swagger-ui`的自动化配置 **(OpenApi3.0规范)**
+- 引入`jackson`并完成序列化和反序列化的配置
+- 自定义`devops-boot`的启动banner
+- 提供常用的工具类和方法
+
+
+## 使用方式
+- **build.gradle.kts**
+
+```kotlin
+implementation("com.tencent.devops:devops-boot-starter-web")
+```
+
+- **build.gradle**
+
+```groovy
+implementation 'com.tencent.devops:devops-boot-starter-web'
+```
+
+## 模块依赖
+`starter-web`添加了如下依赖，对于这些模块的依赖不需要重复声明:
+- `com.tencent.devops:devops-boot-starter-api`
+- `com.tencent.devops:devops-boot-starter-logging`
+
+## 配置属性
+
+- swagger配置过程中会读取以下配置
+  
+  | 属性               | 类型    | 默认值 | 说明               |
+  | ------------------ | ------- | ------ | ------------------ |
+  | spring.application.name  | string | null  | 应用名称，swagger会页面展示该值 |
+  | spring.application.desc  | string | null  | 应用描述，swagger会页面展示该值 |
+  | spring.application.version  | string | null  | 应用版本，swagger会页面展示该值 |
+
+- `springfox starter`[文档地址](http://springfox.github.io/springfox/docs/current/)