bkdevops-projects · carrypann · Jun 21, 2021 · Jun 21, 2021 · Jun 21, 2021
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/_coverpage.md b/docs/_coverpage.md
@@ -0,0 +1,9 @@
+# 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的微服务快速开发框架
+
+[GitHub](https://github.com/bkdevops-projects/devops-framework/)
+[Get Started](/index)
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -0,0 +1,14 @@
+- **入门**
+    - [介绍](/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-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.md)
+- [参与开发](/contribute.md)
+- [更新日志](/changelog.md)
diff --git a/docs/changelog.md 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 → docs/contribute.md b/docs/publish.md → 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`
+- `secrets.SIGNING_PASSWORD`
diff --git a/docs/faq.md b/docs/faq.md
@@ -0,0 +1,4 @@
+# 常见问题
+本篇整理大家经常遇到的一些问题，如有补充，欢迎提交pr
+
+---
diff --git a/docs/index.html b/docs/index.html
@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>devops-boot</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="devops-boot document">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
+</head>
+<body>
+  <div id="app">加载中</div>
+  <script>
+    window.$docsify = {
+      name: 'DevOps-Boot',
+      repo: 'https://github.com/bkdevops-projects/devops-framework/',
+      loadSidebar: true,
+      coverpage: true,
+      maxLevel: 3,
+      subMaxLevel: 2,
+      relativePath: true,
+      search: {
+        placeholder: '输入关键词搜索',
+        noData: '找不到结果!',
+        depth: 3
+      },
+    }
+  </script>
+  <!-- Docsify v4 -->
+  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
+  <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/docsify-copy-code/dist/docsify-copy-code.min.js"></script>
+</body>
+</html>
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,54 @@
+<h1 align="center" style="font-weight: bold;">DevOps Boot</h1>
+<h4 align="center">基于Spring Boot的微服务快速开发框架</h4>
+<div align="center">
+
+[![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)
+
+</div>
+
+----------
+
+## 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/...tools/devops-boot-gradle-plugin/README.md → docs/plugin/devops-boot-gradle-plugin.md b/...tools/devops-boot-gradle-plugin/README.md → docs/plugin/devops-boot-gradle-plugin.md
@@ -14,7 +14,7 @@
 
 如果设置了`kotlin`支持，本插件还会进行如下的额外配置：
 
-- 添加`kotlin jvm`插件, 并配置`kotlin`相关编译选项
+- 添加`kotlin jvm`插件，并配置`kotlin`相关编译选项
 - 添加`spring kotlin`插件，支持`all open`
 - 添加`kotlin-stdlib-jdk8`和`kotlin-std-lib-reflect`依赖
 

diff --git a/docs/plugin/devops-publish-gradle-plugin.md b/docs/plugin/devops-publish-gradle-plugin.md
@@ -0,0 +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<MavenPublication> {
+              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
@@ -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/...tarters/devops-boot-starter-api/README.md → docs/starter/devops-boot-starter-api.md b/...tarters/devops-boot-starter-api/README.md → 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")