From 0babf325e76d72f1d185b4e76b4833860ceb4f09 Mon Sep 17 00:00:00 2001 From: carrypan Date: Mon, 21 Jun 2021 11:25:09 +0800 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20=E5=8F=91=E5=B8=83=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E9=A1=B5=E9=9D=A2=20#65?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/.nojekyll | 0 docs/README.md | 65 +++++++++++++++++++++ docs/_coverpage.md | 16 +++++ docs/_sidebar.md | 17 ++++++ docs/index.html | 31 ++++++++++ docs/plugin/devops-boot-gradle-plugin.md | 1 + docs/plugin/devops-publish-gradle-plugin.md | 1 + docs/starter/devops-boot-starter-logging.md | 1 + 8 files changed, 132 insertions(+) create mode 100644 docs/.nojekyll create mode 100644 docs/README.md create mode 100644 docs/_coverpage.md create mode 100644 docs/_sidebar.md create mode 100644 docs/index.html create mode 100644 docs/plugin/devops-boot-gradle-plugin.md create mode 100644 docs/plugin/devops-publish-gradle-plugin.md create mode 100644 docs/starter/devops-boot-starter-logging.md diff --git a/docs/.nojekyll b/docs/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..48d1462 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,65 @@ +# devops-framework +![GitHub](https://img.shields.io/github/license/bkdevops-projects/devops-framework) +![Maven Central](https://img.shields.io/maven-central/v/com.tencent.devops/devops-boot) +![GitHub Workflow Status (event)](https://img.shields.io/github/workflow/status/bkdevops-projects/devops-framework/build) + + +`devops-framework`是一款基于`Spring Boot`的微服务快速开发框架，提炼自腾讯DevOps团队内部多个项目，使用约定优于配置的设计理念，帮助我们专注于`DevOps`业务快速开发。 + +## 项目特点 +- 提供gradle快速开发插件[devops-boot-gradle-plugin](./devops-boot-project/devops-boot-tools/devops-boot-gradle-plugin/README.md) +- 提供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组件 + - [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** +```groovy +// 添加devops-boot gradle插件 +plugins { + id("com.tencent.devops.boot") version ${version} +} + +dependencies { + // 添加需要的starter组件 + implementation("com.tencent.devops:devops-boot-starter-web") +} +``` +只需要添加`devops-boot`插件，就自动为我们配置好`jdk`版本、编译选项、依赖管理、`kotlin`依赖及`kotlin-spring`插件等等繁琐的配置项。 + +接下来即可直接开始业务逻辑代码的编写了。 + + +## 工程结构 +```shell script +devops-framework/ +├── buildSrc # gradle项目构建目录 +├── devops-boot-project # devops-boot源码目录 +│   ├── devops-boot-core # 核心模块 +│   ├── devops-boot-dependencies # maven bom模块 +│   ├── devops-boot-starters # starter组件目录 +│   └── devops-boot-tools # gradle脚本等工具目录 +├── devops-boot-sample # sample项目 +└── docs # 开发文档 +``` + +## 核心依赖 + +| 依赖 | 版本 | +| ------------ | ------------- | +| JDK | 1.8+ | +| Kotlin | 1.4.32 | +| Gradle | 6.8.3 | +| Spring Boot | 2.3.7.RELEASE | +| Spring Cloud | Hoxton.SR9 | + + +## 发行版本 +- 0.0.1 2020年10月9日 +- 0.0.2 2020年12月22日 +- 0.0.3 2021年1月5日 diff --git a/docs/_coverpage.md b/docs/_coverpage.md new file mode 100644 index 0000000..539a667 --- /dev/null +++ b/docs/_coverpage.md @@ -0,0 +1,16 @@ + + +# DevOps Boot 0.0.3 +![GitHub](https://img.shields.io/github/license/bkdevops-projects/devops-framework) +![Maven Central](https://img.shields.io/maven-central/v/com.tencent.devops/devops-boot) +![GitHub Workflow Status (event)](https://img.shields.io/github/workflow/status/bkdevops-projects/devops-framework/build) + + +> 一款基于Spring Boot的微服务快速开发框架 + +- 提供gradle快速开发插件 +- 提供多个开箱即用的starter组件 +- 帮助我们专注于DevOps业务快速开发 + +[GitHub](https://github.com/bkdevops-projects/devops-framework/) +[Get Started](README.md) diff --git a/docs/_sidebar.md b/docs/_sidebar.md new file mode 100644 index 0000000..d982d18 --- /dev/null +++ b/docs/_sidebar.md @@ -0,0 +1,17 @@ +- **快速入门** + - [简介](README.md) + - [快速开始](quick-start.md) + - [安装配置](install.md) +- **gradle插件** + - [devops-boot-gradle-plugin](/plugin/devops-boot-gradle-plugin.md) + - [devops-publish-gradle-plugin](/plugin/devops-publish-gradle-plugin.md) +- **starter组件** + - [starter-logging](/starter/devops-boot-starter-logging.md) + - [starter-api](/starter/devops-boot-starter-api.md) + - [starter-web](/starter/devops-boot-starter-web.md) + - [starter-service](/starter/devops-boot-starter-service.md) +- **FAQ** + - [常见问题](/faq/faq.md) + - [参与开发](/faq/contribute.md) + - [更新日志](/faq/update.md) + - [如何发布](/publish.md) diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..f4e6d92 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,31 @@ + + + + + DevOps-Boot + + + + + + +
加载中
+ + + + + + diff --git a/docs/plugin/devops-boot-gradle-plugin.md b/docs/plugin/devops-boot-gradle-plugin.md new file mode 100644 index 0000000..dc2c1a3 --- /dev/null +++ b/docs/plugin/devops-boot-gradle-plugin.md @@ -0,0 +1 @@ +# devops-boot-gradle-plugin diff --git a/docs/plugin/devops-publish-gradle-plugin.md b/docs/plugin/devops-publish-gradle-plugin.md new file mode 100644 index 0000000..6bc4c7f --- /dev/null +++ b/docs/plugin/devops-publish-gradle-plugin.md @@ -0,0 +1 @@ +# devops-publish-gradle-plugin diff --git a/docs/starter/devops-boot-starter-logging.md b/docs/starter/devops-boot-starter-logging.md new file mode 100644 index 0000000..3ac4c4d --- /dev/null +++ b/docs/starter/devops-boot-starter-logging.md @@ -0,0 +1 @@ +# devops-boot-starter-logging.md From eb662f655a316a452651d53a2b1173ccdd50f96a Mon Sep 17 00:00:00 2001 From: carrypan Date: Mon, 21 Jun 2021 17:17:07 +0800 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20=E5=8F=91=E5=B8=83=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E9=A1=B5=E9=9D=A2=20#65?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../devops-boot-starter-logging/README.md | 46 ------ .../devops-boot-gradle-plugin/README.md | 48 ------ docs/README.md | 65 --------- docs/_coverpage.md | 13 +- docs/_sidebar.md | 17 +-- docs/changelog.md | 34 +++++ docs/{publish.md => contribute.md} | 19 ++- docs/faq.md | 4 + docs/index.html | 9 +- docs/index.md | 54 +++++++ docs/plugin/devops-boot-gradle-plugin.md | 47 ++++++ docs/plugin/devops-publish-gradle-plugin.md | 138 ++++++++++++++++++ docs/quick-start.md | 19 +++ .../starter/devops-boot-starter-api.md | 4 +- docs/starter/devops-boot-starter-logging.md | 47 +++++- .../starter/devops-boot-starter-service.md | 0 .../starter/devops-boot-starter-web.md | 4 +- 17 files changed, 379 insertions(+), 189 deletions(-) delete mode 100644 devops-boot-project/devops-boot-starters/devops-boot-starter-logging/README.md delete mode 100644 devops-boot-project/devops-boot-tools/devops-boot-gradle-plugin/README.md delete mode 100644 docs/README.md create mode 100644 docs/changelog.md rename docs/{publish.md => contribute.md} (60%) create mode 100644 docs/faq.md create mode 100644 docs/index.md create mode 100644 docs/quick-start.md rename devops-boot-project/devops-boot-starters/devops-boot-starter-api/README.md => docs/starter/devops-boot-starter-api.md (91%) rename devops-boot-project/devops-boot-starters/devops-boot-starter-service/README.md => docs/starter/devops-boot-starter-service.md (100%) rename devops-boot-project/devops-boot-starters/devops-boot-starter-web/README.md => docs/starter/devops-boot-starter-web.md (95%) diff --git a/devops-boot-project/devops-boot-starters/devops-boot-starter-logging/README.md b/devops-boot-project/devops-boot-starters/devops-boot-starter-logging/README.md deleted file mode 100644 index 7388ecb..0000000 --- a/devops-boot-project/devops-boot-starters/devops-boot-starter-logging/README.md +++ /dev/null @@ -1,46 +0,0 @@ -# devops-boot-starter-logging - -logging组件帮助开发者完成日志的快速配置，并统一日志格式。 - -## 功能介绍 - - 基于`slf4j`+`logback` - - 提供`logback`基础配置文件，支持`include`方式引入 - - `base.xml` 基础属性配置 - - `appender.xml` `appender`配置 - - 配置统一的日志打印格式 - - 配置统一的日志输出位置 - - 配置统一的日志切割策略 - - 配置统一的异步日志输出 - - 约定统一的日志分类方式 - - 访问日志: {application}-access.log - - 应用日志: {application}-app.log - - 错误日志: {application}-error.log - -## 使用方式 -- **build.gradle.kts** - -```kotlin -implementation("com.tencent.devops:devops-boot-starter-logging") -``` - -- **build.gradle** - -```groovy -implementation 'com.tencent.devops:devops-boot-starter-logging' -``` - -## 配置属性 - -| 属性 | 类型 | 默认值 | 说明 | -| ------------------ | ------- | ------ | ------------------ | -| logging.file.path | string | ./ | 日志输出位置，默认当前目录 | -| logging.level.\ | string | INFO | 调整`loggerName`日志级别, `root`代表所有logger | - -## 说明 - -logging组件会自动根据不同的`profile`应用不同的appender配置 - -| profile | 初始日志级别 | appender | -| ------------------------- | ----------- | ----------------- | -| `default`、`local`、`dev` | INFO | `console`、`file` | -| `test`、`prod` | INFO | `file` | diff --git a/devops-boot-project/devops-boot-tools/devops-boot-gradle-plugin/README.md b/devops-boot-project/devops-boot-tools/devops-boot-gradle-plugin/README.md deleted file mode 100644 index 4d7161e..0000000 --- a/devops-boot-project/devops-boot-tools/devops-boot-gradle-plugin/README.md +++ /dev/null @@ -1,48 +0,0 @@ -# devops-boot-gradle-plugin - -## 功能介绍 - -`devops-boot-gradle-plugin`是一个用于快速构建`Spring Boot`应用程序的gradle插件，引入该插件后，会为我们自动完成： - -- 配置jdk插件及编译选项，默认版本为1.8 -- 配置maven仓库列表，除中央仓库之外还添加了腾讯源 -- 添加`spring boot`相关插件 -- 添加依赖管理插件，并引入`devops-boot-dependencies`基础依赖`bom` -- 配置`JUnit`相关支持及依赖 -- 支持配置是否引入`kotlin` -- 支持配置`jdk`版本 - -如果设置了`kotlin`支持，本插件还会进行如下的额外配置： - -- 添加`kotlin jvm`插件, 并配置`kotlin`相关编译选项 -- 添加`spring kotlin`插件，支持`all open` -- 添加`kotlin-stdlib-jdk8`和`kotlin-std-lib-reflect`依赖 - - -## 使用方式 - -- **build.gradle.kts** - -```groovy -plugins { - id("devops-boot-gradle-plugin") version ${version} -} -``` - -- **build.gradle** - -```groovy -plugins { - id 'devops-boot-gradle-plugin' version ${version} -} -``` - -## 配置属性 - -支持在`gradle.properties`中进行如下配置: - -| 属性 | 类型 | 默认值 | 说明 | -| ------------------ | ------- | ------ | ------------------ | -| devops.kotlin | boolean | true | 是否添加kotlin支持 | -| devops.javaVersion | string | 1.8 | jdk版本 | - diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 48d1462..0000000 --- a/docs/README.md +++ /dev/null @@ -1,65 +0,0 @@ -# devops-framework -![GitHub](https://img.shields.io/github/license/bkdevops-projects/devops-framework) -![Maven Central](https://img.shields.io/maven-central/v/com.tencent.devops/devops-boot) -![GitHub Workflow Status (event)](https://img.shields.io/github/workflow/status/bkdevops-projects/devops-framework/build) - - -`devops-framework`是一款基于`Spring Boot`的微服务快速开发框架，提炼自腾讯DevOps团队内部多个项目，使用约定优于配置的设计理念，帮助我们专注于`DevOps`业务快速开发。 - -## 项目特点 -- 提供gradle快速开发插件[devops-boot-gradle-plugin](./devops-boot-project/devops-boot-tools/devops-boot-gradle-plugin/README.md) -- 提供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组件 - - [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** -```groovy -// 添加devops-boot gradle插件 -plugins { - id("com.tencent.devops.boot") version ${version} -} - -dependencies { - // 添加需要的starter组件 - implementation("com.tencent.devops:devops-boot-starter-web") -} -``` -只需要添加`devops-boot`插件，就自动为我们配置好`jdk`版本、编译选项、依赖管理、`kotlin`依赖及`kotlin-spring`插件等等繁琐的配置项。 - -接下来即可直接开始业务逻辑代码的编写了。 - - -## 工程结构 -```shell script -devops-framework/ -├── buildSrc # gradle项目构建目录 -├── devops-boot-project # devops-boot源码目录 -│   ├── devops-boot-core # 核心模块 -│   ├── devops-boot-dependencies # maven bom模块 -│   ├── devops-boot-starters # starter组件目录 -│   └── devops-boot-tools # gradle脚本等工具目录 -├── devops-boot-sample # sample项目 -└── docs # 开发文档 -``` - -## 核心依赖 - -| 依赖 | 版本 | -| ------------ | ------------- | -| JDK | 1.8+ | -| Kotlin | 1.4.32 | -| Gradle | 6.8.3 | -| Spring Boot | 2.3.7.RELEASE | -| Spring Cloud | Hoxton.SR9 | - - -## 发行版本 -- 0.0.1 2020年10月9日 -- 0.0.2 2020年12月22日 -- 0.0.3 2021年1月5日 diff --git a/docs/_coverpage.md b/docs/_coverpage.md index 539a667..5af3cdb 100644 --- a/docs/_coverpage.md +++ b/docs/_coverpage.md @@ -1,16 +1,9 @@ - - -# DevOps Boot 0.0.3 +# DevOps Boot ![GitHub](https://img.shields.io/github/license/bkdevops-projects/devops-framework) ![Maven Central](https://img.shields.io/maven-central/v/com.tencent.devops/devops-boot) ![GitHub Workflow Status (event)](https://img.shields.io/github/workflow/status/bkdevops-projects/devops-framework/build) - -> 一款基于Spring Boot的微服务快速开发框架 - -- 提供gradle快速开发插件 -- 提供多个开箱即用的starter组件 -- 帮助我们专注于DevOps业务快速开发 +> 基于Spring Boot的微服务快速开发框架 [GitHub](https://github.com/bkdevops-projects/devops-framework/) -[Get Started](README.md) +[Get Started](/index) diff --git a/docs/_sidebar.md b/docs/_sidebar.md index d982d18..021fad0 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1,17 +1,14 @@ -- **快速入门** - - [简介](README.md) - - [快速开始](quick-start.md) - - [安装配置](install.md) +- **入门** + - [介绍](/index.md) + - [快速开始](/quick-start.md) - **gradle插件** - [devops-boot-gradle-plugin](/plugin/devops-boot-gradle-plugin.md) - [devops-publish-gradle-plugin](/plugin/devops-publish-gradle-plugin.md) - **starter组件** - - [starter-logging](/starter/devops-boot-starter-logging.md) - [starter-api](/starter/devops-boot-starter-api.md) + - [starter-logging](/starter/devops-boot-starter-logging.md) - [starter-web](/starter/devops-boot-starter-web.md) - [starter-service](/starter/devops-boot-starter-service.md) -- **FAQ** - - [常见问题](/faq/faq.md) - - [参与开发](/faq/contribute.md) - - [更新日志](/faq/update.md) - - [如何发布](/publish.md) +- [常见问题](/faq.md) +- [参与开发](/contribute.md) +- [更新日志](/changelog.md) diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 0000000..94bb73e --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,34 @@ +## [0.0.3](https://github.com/bkdevops-projects/devops-framework/releases/tag/0.0.3) (2021-01-05) + +### Features +- 开发api公共组件 +- 开发web公共组件 +- 开发service公共组件 +- 提供HTTP常用枚举和常量 + +### Docs +- 补全文档 + +## [0.0.2](https://github.com/bkdevops-projects/devops-framework/releases/tag/0.0.2) (2020-12-22) + +### Features +- devops-boot-gradle-plugin仓库列表添加mavenLocal +- 开发devops-publish-gradle-plugin插件 + +### Chore +- 合并pr后才触发publish snapshot + +### Refactor +- gradle插件自动过滤空模块 +- 优化devops-boot-gradle-plugin + +### Dependencies +- 添加公共依赖版本管理 +- 添加公共依赖版本管理 + +## [0.0.1](https://github.com/bkdevops-projects/devops-framework/releases/tag/0.0.1) (2020-10-09) + +### Features: +- 开发devops boot gradle插件 +- 开发devops dependencies 依赖管理bom +- 开发devops-logging-starter 日志组件 diff --git a/docs/publish.md b/docs/contribute.md similarity index 60% rename from docs/publish.md rename to docs/contribute.md index 61bcb11..00f85ed 100644 --- a/docs/publish.md +++ b/docs/contribute.md @@ -1,3 +1,18 @@ +## 工程结构 +?> 待完善 + +```shell script +devops-framework/ +├── buildSrc # gradle项目构建目录 +├── devops-boot-project # devops-boot源码目录 +│   ├── devops-boot-core # 核心模块 +│   ├── devops-boot-dependencies # maven bom模块 +│   ├── devops-boot-starters # starter组件目录 +│   └── devops-boot-tools # gradle脚本等工具目录 +├── devops-boot-sample # sample项目 +└── docs # 项目文档 +``` + ## How to publish to maven repository? ### 发布命令 @@ -29,7 +44,7 @@ 会自动读取以下`github secrets`并设置为对应的环境变量： - `secrets.SONATYPE_USERNAME` -- `secrets.SONATYPE_PASSWORD` +- `secrets.SONATYPE_PASSWORD` - `secrets.SIGNING_KEY` - `secrets.SIGNING_KEY_ID` -- `secrets.SIGNING_PASSWORD` \ No newline at end of file +- `secrets.SIGNING_PASSWORD` diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..0792a13 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,4 @@ +# 常见问题 +本篇整理大家经常遇到的一些问题，如有补充，欢迎提交pr + +--- diff --git a/docs/index.html b/docs/index.html index f4e6d92..b8d9113 100644 --- a/docs/index.html +++ b/docs/index.html @@ -2,7 +2,7 @@ - DevOps-Boot + devops-boot @@ -12,10 +12,12 @@
加载中
+ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..b1fe005 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,54 @@ +

DevOps Boot

+

基于Spring Boot的微服务快速开发框架

+
+ +[![GitHub](https://img.shields.io/github/license/bkdevops-projects/devops-framework)](https://img.shields.io/github/license/bkdevops-projects/devops-framework) +[![Maven Central](https://img.shields.io/maven-central/v/com.tencent.devops/devops-boot)](https://img.shields.io/maven-central/v/com.tencent.devops/devops-boot) +[![GitHub Workflow Status (event)](https://img.shields.io/github/workflow/status/bkdevops-projects/devops-framework/build)](https://img.shields.io/github/workflow/status/bkdevops-projects/devops-framework/build) + +
+ +---------- + +## DevOps Boot 是什么？ + +`devops-boot`提炼自腾讯DevOps团队内部多个项目，使用约定优于配置的设计理念，帮助我们专注于DevOps业务快速开发，它具有以下优势: + +- **简单** ：几乎零配置快速开发微服务，低成本上手 +- **易用** ：采用`Spring Boot`组件化思想，易于学习理解 +- **统一** ：目前已集成了微服务开发常用组件和统一配置 +- **扩展** ：组件之间低耦合，高内聚，扩展十分方便 + +查看[快速开始](quick-start.md)了解详情。 + +## DevOps Boot 能解决什么问题？ + +- **统一项目配置** ： 免去繁琐的项目配置，gradle插件帮您解决烦恼 +- **统一依赖版本管理** ： 多个项目统一jdk和三方依赖版本，避免版本冲突 +- **统一微服务治理解决方案**： 解决多个项目技术方案参差不齐，架构不统一问题 +- **统一常用工具类** ： 避免代码重复 + +## 功能特性 +- 提供gradle快速开发插件[devops-boot-gradle-plugin](./devops-boot-project/devops-boot-tools/devops-boot-gradle-plugin/README.md) +- 提供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组件 + - [starter-api](./devops-boot-project/devops-boot-starters/devops-boot-starter-api/README.md) + - [starter-logging](./devops-boot-project/devops-boot-starters/devops-boot-starter-logging/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) + - ... + +## 核心依赖 + +| 依赖 | 版本 | +| ------------ | ------------- | +| JDK | 1.8+ | +| Kotlin | 1.4.32 | +| Gradle | 6.8.3 | +| Spring Boot | 2.4.5 | +| Spring Cloud | 2020.0.2 | + +## 示例 + +可以查看[sample](https://github.com/bkdevops-projects/devops-framework/tree/master/devops-boot-sample)来了解如何优雅集成`devops-boot`框架。 diff --git a/docs/plugin/devops-boot-gradle-plugin.md b/docs/plugin/devops-boot-gradle-plugin.md index dc2c1a3..dc0e0bd 100644 --- a/docs/plugin/devops-boot-gradle-plugin.md +++ b/docs/plugin/devops-boot-gradle-plugin.md @@ -1 +1,48 @@ # devops-boot-gradle-plugin + +## 功能介绍 + +`devops-boot-gradle-plugin`是一个用于快速构建`Spring Boot`应用程序的gradle插件，引入该插件后，会为我们自动完成： + +- 配置jdk插件及编译选项，默认版本为1.8 +- 配置maven仓库列表，除中央仓库之外还添加了腾讯源 +- 添加`spring boot`相关插件 +- 添加依赖管理插件，并引入`devops-boot-dependencies`基础依赖`bom` +- 配置`JUnit`相关支持及依赖 +- 支持配置是否引入`kotlin` +- 支持配置`jdk`版本 + +如果设置了`kotlin`支持，本插件还会进行如下的额外配置： + +- 添加`kotlin jvm`插件，并配置`kotlin`相关编译选项 +- 添加`spring kotlin`插件，支持`all open` +- 添加`kotlin-stdlib-jdk8`和`kotlin-std-lib-reflect`依赖 + + +## 使用方式 + +- **build.gradle.kts** + +```groovy +plugins { + id("devops-boot-gradle-plugin") version ${version} +} +``` + +- **build.gradle** + +```groovy +plugins { + id 'devops-boot-gradle-plugin' version ${version} +} +``` + +## 配置属性 + +支持在`gradle.properties`中进行如下配置: + +| 属性 | 类型 | 默认值 | 说明 | +| ------------------ | ------- | ------ | ------------------ | +| devops.kotlin | boolean | true | 是否添加kotlin支持 | +| devops.javaVersion | string | 1.8 | jdk版本 | + diff --git a/docs/plugin/devops-publish-gradle-plugin.md b/docs/plugin/devops-publish-gradle-plugin.md index 6bc4c7f..87c3fa6 100644 --- a/docs/plugin/devops-publish-gradle-plugin.md +++ b/docs/plugin/devops-publish-gradle-plugin.md @@ -1 +1,139 @@ # devops-publish-gradle-plugin + +## 功能介绍 + +`devops-publish-gradle-plugin`是一个用于快速发布jar到maven中央仓库或私有maven仓库的gradle插件。 + +插件本身基于gradle官方推荐的`maven-publish`插件，我们在不破坏其本身用法的原则上，自动完成以下内容： + +- 添加`maven-publish`插件，该插件为gradle官方推荐的jar包发布插件 +- 添加`signing`签名插件，该插件为gradle官方推荐的jar包签名插件 +- 自动配置签名信息 +- 自动配置`javaSource`、`javaDoc`等`publications` +- 自动配置发布仓库信息`repositories`，根据版本号自动选择`repository` +- 自动补全`manifest`信息 + +`devops-publish-gradle-plugin`插件可以为我们解决以下问题： +1. `SONATYPE`中央仓库对于jar包的规范十分严格，如`manifest`文件、`pom`信息、签名规范等，任何一个环节出错都会导致发布失败 +2. 远程仓库信息配置方式不统一 +3. GPG签名配置方式不统一 + +## 使用方式 + +对于需要发布到中央仓库或私服的`module`: + +- **build.gradle.kts** + +```groovy +plugins { + id("devops-publish-gradle-plugin") version ${version} +} +``` + +- **build.gradle** + +```groovy +plugins { + id 'devops-publish-gradle-plugin' version ${version} +} +``` + +## 配置属性 + +### 优先级 + +为了适配ci流水线、本地开发等各种环境，且避免敏感信息泄露，插件会按照以下顺序查找配置(优先级越高越靠前)： + +1. 命令行变量 + +```shell +gradle -Dkey=value +``` + +2. 环境变量 + +```shell +export key=value +``` + +3. `gradle.properties` + +``` +key=value +``` + +### 远程仓库信息 + +| 属性 | 类型 | 默认值 | 说明 | +| --------------- | ------- | ------ | ---------- | +| releaseRepoUrl | string | [https://oss.sonatype.org/service/local/](https://oss.sonatype.org/service/local/) | release仓库地址，默然为SONATYPE中央仓库地址 | +| snapshotRepoUrl | string | [https://oss.sonatype.org/content/repositories/snapshots/](https://oss.sonatype.org/content/repositories/snapshots/) | snapshot仓库地址，默然为SONATYPE中央仓库地址 | +| repoUsername | string | null | 仓库认证用户名 | +| repoPassword | string | null | 仓库认证密码 | + + +### 签名信息 + +| 属性 | 类型 | 默认值 | 说明 | +| --------------- | ------- | ------ | ----------- | +| signingKey | string | null | gpg签名key | +| signingKeyId | string | null | gpg签名keyId | +| signingPassword | string | null | gpg签名password | + + +## 说明 + +- 插件会读取`project.version`变量得到版本号，如果版本号以`SNAPSHOT`结尾，则使用`snapshotRepoUrl`进行发布，且不会执行签名，`SONATYPE`只会对release包进行签名校验。 + +- 获取gpg 信息 + ```shell + # secret key, signingKeyId取该值 + gpg --armor --export-secret-key username@email --output private.key + + # public key + gpg --armor --export username@email --output public.key + + # keyId，取pub最后8位 + gpg --list-keys + ``` + +- 自定义pom信息 + + ```kotlin + publishing { + publications { + withType { + pom { + name.set(project.name) + description.set(project.description ?: project.name) + url.set("https://github.com/Tencent/bk-ci") + licenses { + license { + name.set("The MIT License (MIT)") + url.set("https://opensource.org/licenses/MIT") + } + } + developers { + developer { + name.set("bk-ci") + email.set("devops@tencent.com") + url.set("https://bk.tencent.com") + roles.set(listOf("Manager")) + } + } + scm { + connection.set("scm:git:git://github.com/Tencent/bk-ci.get") + developerConnection.set("scm:git:ssh://github.com/Tencent/bk-ci.git") + url.set("https://github.com/Tencent/bk-ci") + } + } + } + } + } + ``` + + +## 参考 + +- [`maven-publish`插件官方教程](https://docs.gradle.org/current/userguide/publishing_maven.html) +- [`signing`插件官方教程](https://docs.gradle.org/current/userguide/signing_plugin.html) diff --git a/docs/quick-start.md b/docs/quick-start.md new file mode 100644 index 0000000..0bfd972 --- /dev/null +++ b/docs/quick-start.md @@ -0,0 +1,19 @@ +# 快速开始 +?> 待完善 + +- **gradle.build.kts** + ```kotlin + // 添加devops-boot gradle插件 + plugins { + id("com.tencent.devops.boot") version ${version} + } + + dependencies { + // 添加需要的starter组件 + implementation("com.tencent.devops:devops-boot-starter-web") + } + ``` + +只需要添加`devops-boot`插件，就自动为我们配置好`jdk`版本、编译选项、依赖管理、`kotlin`依赖及`kotlin-spring`插件等等繁琐的配置项。 + +接下来即可直接开始业务逻辑代码的编写了。 diff --git a/devops-boot-project/devops-boot-starters/devops-boot-starter-api/README.md b/docs/starter/devops-boot-starter-api.md similarity index 91% rename from devops-boot-project/devops-boot-starters/devops-boot-starter-api/README.md rename to docs/starter/devops-boot-starter-api.md index 2cb6a34..f38eddf 100644 --- a/devops-boot-project/devops-boot-starters/devops-boot-starter-api/README.md +++ b/docs/starter/devops-boot-starter-api.md @@ -24,11 +24,11 @@ implementation 'com.tencent.devops:devops-boot-starter-api' 项目的`api`模块包含了对外接口的声明以及数据格式的定义，最终作为二方包或者三方包提供给对外使用，因此需要开发者保持`api`模块的精简和规范，否则会引诸多问题，如： 1. 不规范的依赖声明方式导致版本依赖冲突 -2. 引入过多/多余的依赖，导致臃肿 +2. 引入过多&多余的依赖，导致模块臃肿 3. 在`api`模块中暴露敏感信息，如`DO`类 `starter-api`组件秉承这一理念，帮助开发者最大化精简和规范`api`模块的开发，但开发者仍然需要注意以下事项： -1. `api`模块慎重引入依赖，如需引入请考楼`implementation`或`comipleOnly`方式 +1. `api`模块慎重引入依赖，如需引入请使用`implementation`或`comipleOnly`方式 2. 对于`@RequestMapping`、`@FeignClient`注解的依赖，使用`comipleOnly`的方式依赖 ```kotlin compileOnly("org.springframework.cloud:spring-cloud-openfeign-core") diff --git a/docs/starter/devops-boot-starter-logging.md b/docs/starter/devops-boot-starter-logging.md index 3ac4c4d..25f3f40 100644 --- a/docs/starter/devops-boot-starter-logging.md +++ b/docs/starter/devops-boot-starter-logging.md @@ -1 +1,46 @@ -# devops-boot-starter-logging.md +# devops-boot-starter-logging + +`starter-logging`组件帮助开发者完成日志的快速配置，并统一日志格式 + +## 功能介绍 +- 基于`slf4j`+`logback` +- 提供`logback`基础配置文件，支持`include`方式引入 + - `base.xml` 基础属性配置 + - `appender.xml` `appender`配置 +- 配置统一的日志打印格式 +- 配置统一的日志输出位置 +- 配置统一的日志切割策略 +- 配置统一的异步日志输出 +- 约定统一的日志分类方式 + - 访问日志: {application}-access.log + - 应用日志: {application}-app.log + - 错误日志: {application}-error.log + +## 使用方式 +- **build.gradle.kts** + +```kotlin +implementation("com.tencent.devops:devops-boot-starter-logging") +``` + +- **build.gradle** + +```groovy +implementation 'com.tencent.devops:devops-boot-starter-logging' +``` + +## 配置属性 + +| 属性 | 类型 | 默认值 | 说明 | +| ------------------ | ------- | ------ | ------------------ | +| logging.file.path | string | ./ | 日志输出位置，默认当前目录 | +| logging.level.\ | string | INFO | 调整`loggerName`日志级别, `root`代表所有logger | + +## 说明 + +logging组件会自动根据不同的`profile`应用不同的appender配置 + +| profile | 初始日志级别 | appender | +| ------------------------- | ----------- | ----------------- | +| `default`、`local`、`dev` | INFO | `console`、`file` | +| `test`、`prod` | INFO | `file` | diff --git a/devops-boot-project/devops-boot-starters/devops-boot-starter-service/README.md b/docs/starter/devops-boot-starter-service.md similarity index 100% rename from devops-boot-project/devops-boot-starters/devops-boot-starter-service/README.md rename to docs/starter/devops-boot-starter-service.md diff --git a/devops-boot-project/devops-boot-starters/devops-boot-starter-web/README.md b/docs/starter/devops-boot-starter-web.md similarity index 95% rename from devops-boot-project/devops-boot-starters/devops-boot-starter-web/README.md rename to docs/starter/devops-boot-starter-web.md index 48ee188..e8362e5 100644 --- a/devops-boot-project/devops-boot-starters/devops-boot-starter-web/README.md +++ b/docs/starter/devops-boot-starter-web.md @@ -32,9 +32,9 @@ implementation 'com.tencent.devops:devops-boot-starter-web' ## 配置属性 - swagger配置过程中会读取以下配置 - + | 属性 | 类型 | 默认值 | 说明 | - | ------------------ | ------- | ------ | ------------------ | + | ------------------ | ------- | ------ | ------------------ | | spring.application.name | string | null | 应用名称，swagger会页面展示该值 | | spring.application.desc | string | null | 应用描述，swagger会页面展示该值 | | spring.application.version | string | null | 应用版本，swagger会页面展示该值 |