# zero

**Repository Path**: orange-swallow/zero

## Basic Information

- **Project Name**: zero
- **Description**: 一个自己用的后台管理系统
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-09-16
- **Last Updated**: 2026-02-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# genesis

![Static Badge](https://shields-shields.apps.dian-int.com/badge/jdk-21-brightgreen) ![Static Badge](https://shields-shields.apps.dian-int.com/badge/spring-framework-brightgreen)

# 介绍
基于springboot 3.2.4构建的微服务开发工程，包含了nacos/openTelemetry/mybatis/redis等常用组件的使用，默认使用Jenkins作为持续集成方案，更新JenkinsFile配置文件，即可实现持续集成。

# 相关链接

- [Jenkins CI Documentation](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/)
- [SpringBoot Overview](https://spring.io/projects/spring-framework/)

# 开始

## 目录结构

- src/main/java 源码
- src/main/resources 应用配置
- src/test/java 单测源码
- src/test/resources 单测配置
- .mvnw - 指定maven版本 -> 3.9.5

```shell
genesis
├── .mvn
├── src/test/java/so/dian/genesis
├── src/main/java/so/dian/genesis
│   └── config
│   └── controller
└── src/main/resources
```

### 健康检查
1. 引言\
Actuator 主要提供了以下功能：
- 健康检查：检查应用的健康状况，比如数据库连接是否正常，磁盘空间是否充足等。
- 度量信息：收集和展示应用的各种度量指标，如 JVM 内存使用情况，HTTP 请求统计等。
- 审计：跟踪应用中的重要事件，比如登录失败、权限更改等。
- 环境信息：展示应用的配置信息，包括环境变量、系统属性等。
- 日志级别管理：动态调整应用的日志级别。
- Actuator 通过 HTTP 端点的形式暴露这些信息，使得您可以方便地在运行时查看和管理应用。
2. 启用健康检查端点
- 默认在nacos中配置开启management.endpoints.web.exposure.include=*
- 默认端口management.server.port=8888
3. 访问健康检查端点
- 查看暴露的端点 http://localhost:8888/actuator
- 健康检查端点 http://localhost:8888/actuator/health
4. 自定义健康指标
- 如何实现 HealthIndicator 接口
```java
@Component
public class MyHealthIndicator implements HealthIndicator {

	@Override
	public Health health() {
		int errorCode = check();
		if (errorCode != 0) {
			return Health.down().withDetail("Error Code", errorCode).build();
		}
		return Health.up().build();
	}

	private int check() {
		// perform some specific health check
		return ...
	}

}
```
5. 参考文档
- [SpringBoot Actuator](https://docs.spring.io/spring-boot/docs/3.2.4/reference/htmlsingle/#actuator)

### OpenTelemetry链路监控
1. 引言\
OpenTelemetry 是一个用于观测性（Observability）的开放源代码框架，支持trace、metric和log记录。它旨在帮助开发者和运维人员在复杂的分布式系统中，更好地追踪和监控请求的传递和处理。
2. pom依赖
```xml
<!-- feign client监控 -->
<dependency>
<groupId>io.github.openfeign</groupId>
<artifactId>feign-micrometer</artifactId>
</dependency>
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-registry-otlp</artifactId>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-tracing-bridge-otel</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry.instrumentation</groupId>
<artifactId>opentelemetry-logback-mdc-1.0</artifactId>
<scope>runtime</scope>
</dependency>
<!-- datasource监控 -->
<dependency>
<groupId>net.ttddyy.observation</groupId>
<artifactId>datasource-micrometer-spring-boot</artifactId>
<version>${datasource-micrometer.version}</version>
</dependency>
```
3. 默认在nacos中配置开启\
配置 OpenTelemetry 将数据发送到collector,默认http协议
```yaml
management:
otlp:
	metrics:
	export:
		enabled: false # 是否开启metrics采集
	tracing:
	endpoint: https://otlp-http.otel-preview-for-prod.apps.dian-int.com/v1/traces # 采集地址
tracing:
	sampling:
	probability: 1.0 # 采样率
opentelemetry:
	resource-attributes:
	service.name: ${spring.application.name}
	service.version: 1.0.0
	env: ${spring.profiles.active}
observations:
	annotations:
	enabled: true
```
4. 配置过滤掉健康检查和option等无效trace
```java
@Bean
ObservationPredicate noActuatorServerObservations() {
return (name, context) -> {
if (name.equals("http.server.requests")
	&& context instanceof ServerRequestObservationContext serverContext) {
	return !serverContext.getCarrier().getRequestURI().startsWith("/actuator")
		|| !serverContext.getCarrier().getRequestURI().startsWith("/api-docs")
		|| !serverContext.getCarrier().getRequestURI().startsWith("/swagger-ui")
		|| serverContext.getCarrier().getMethod().equals("OPTIONS");
} else {
	return Objects.nonNull(context.getParentObservation());
}
};
}
```
5. 参考文档
- [opentelemetry](https://opentelemetry.io/docs/languages/java/automatic/spring-boot/)
- [micrometer- OpenTelemetry Protocol (OTLP)](https://docs.micrometer.io/micrometer/reference/implementations/otlp.html)
- [micrometer-tracing](https://docs.micrometer.io/tracing/reference/index.html)
- [springboot-observability](https://docs.spring.io/spring-data/redis/reference/observability.html)
6. 链路监控查看入口
- [otel-preview](https://sls.console.aliyun.com/lognext/app/observability/trace/otel-preview/otel-preview?resource=%2Ftrace%2Fotel-preview%2Fdependence)


## 依赖项

1. 添加依赖项
```xml
<properties>
	<dian-logger.version>2.0.2</dian-logger.version>
</properties>
<dependencies>
	<dependency>
		<groupId>so.dian.common</groupId>
		<artifactId>dian-logger</artifactId>
		<version>${dian-logger.version}</version>
	</dependency>
</dependencies>
```

2. 检查依赖冲突
```shell
$ ./mvnw validate
```

## maven插件
### 1. spotless-maven-plugin
检查Java源文件是否与代码规范相符，默认为Google-style
主要包括：
- Javadoc注释
- 命名规范
- 多余没用的Imports
- Size度量，如过长的方法
- 缺少必要的空格Whitespace
- 重复代码
```shell
$ ./mvnw spoless:check //检查代码风格是否符合规范
$ ./mvnw spoless:apply //格式化工程代码
```

### 2. maven-enforcer-plugin
检查依赖项冲突
```shell
$ ./mvnw validate
```

### 3. mybatis-generator-maven-plugin
根据数据库表结构自动生成Mapper.xml和Entity.java, 插件配置参考[mybatis-generator-maven-plugin](https://mybatis.org/generator/reference/plugins/index.html)
```shell
$ ./mvnw mybatis-generator:generate
```
> 修改生成配置：generator/generatorConfig.xml和generator/generator.properties

### 4. jacoco-maven-plugin
生成单测覆盖率
```shell
$ ./mvnw test
```

### 5. jib-maven-plugin
应用镜像基于jdk 21版本，需要更新镜像，请更新`configuration/from/image`中的镜像地址
```xml
<plugin>
	<groupId>com.google.cloud.tools</groupId>
	<artifactId>jib-maven-plugin</artifactId>
	<version>${jib-maven.version}</version>
	<dependencies>
		<dependency>
			<groupId>com.google.cloud.tools</groupId>
			<artifactId>jib-layer-filter-extension-maven</artifactId>
			<version>0.3.0</version>
		</dependency>
	</dependencies>
	<configuration>
		<containerizingMode>packaged</containerizingMode>
		<container>
			<appRoot>/deployments</appRoot>
			<entrypoint>/opt/jboss/container/java/run/run-java.sh</entrypoint>
		</container>
		<extraDirectories>
			<paths>
				<path>
					<from>target/</from>
					<includes>*.jar</includes>
					<into>/deployments</into>
				</path>
			</paths>
		</extraDirectories>
		<pluginExtensions>
			<pluginExtension>
				<implementation>
					com.google.cloud.tools.jib.maven.extension.layerfilter.JibLayerFilterExtension
				</implementation>
				<configuration
						implementation="com.google.cloud.tools.jib.maven.extension.layerfilter.Configuration">
					<filters>
						<filter>
							<!-- exclude all jib layers, which is basically anything in /app -->
							<glob>/deployments/**</glob>
						</filter>
						<filter>
							<!-- this is our fat jar, this should be kept by adding it into its own layer -->
							<glob>/deployments/${project.build.finalName}.jar</glob>
							<toLayer>jib-custom-fatJar</toLayer>
						</filter>
					</filters>
				</configuration>
			</pluginExtension>
		</pluginExtensions>
		<from>
			<image>
				quay.xiaodiankeji.net/openjdk/openjdk-21-runtime-skywalking@sha256:ccb808d7b43ff2f411e329ef9d746d20378886968e86e7035ebc1661f283c67c
			</image>
			<platforms>
				<platform>
					<architecture>arm64</architecture>
					<os>linux</os>
				</platform>
				<platform>
					<architecture>amd64</architecture>
					<os>linux</os>
				</platform>
			</platforms>
		</from>
	</configuration>
</plugin>
```

## [Jenkinsfile](Jenkinsfile)

1. 加载模版库
```groovy
@Library('jenkins-pipeline-library@main') _
```

2. 持续集成任务：
- 单元测试
- 静态代码扫描（集成sonar）
- 依赖项快照版本检查
- snyk安全扫描
- 构建镜像
- 发布镜像
- 部署到k8s测试集群

> 查看jenkins模版库 [jenkins-pipeline-template](https://git.dian.so/devops/jenkins-pipeline-library/-/tree/main), 分支`main`

## [KubernetesPod](KubernetesPod.yaml)
应用构建基于openjdk 21版本，升级jdk版本需要修改openjdk镜像
```yaml
spec:
containers:
- args:
	- "while true; do sleep infinity || exit 0; done"
	command:
	- "/bin/sh"
	- "-c"
	image: "quay.xiaodiankeji.net/redhat-cache/ubi9/openjdk-21:latest"
	name: "java"
	volumeMounts:
	- mountPath: "/home/default/.m2/settings.xml"
	name: "volume-0"
	readOnly: false
	subPath: "settings.xml"
	- mountPath: "/.m2"
	name: "volume-1"
	readOnly: false
	workingDir: "/tmp/src"
```

## 编译源码

```shell
$ ./mvnw clean install -DskipTests=true
```

## 运行服务

```shell
$ ./mvnw spring-boot:run -Dspring-boot.run.jvmArguments=-Dspring.profiles.active=dev
```

## 徽章图标
>
> 制作自定义徽章图标 <https://shields-shields.apps.dian-int.com/badges>

1. 制作编译状态徽章图标, 打开[Jenkins](https://dna-jenkins-2.xiaodiankeji.net/jenkins/), 选择项目，打开主分支任务，拷贝url, 打开[制作徽章](https://shields-shields.apps.dian-int.com/badges), Jenkins Build 粘贴url，点击“Generate badge”
2. 制作代码质量徽章图标，打开[SonarQube](https://sonar.xiaodiankeji.net/project)，选择项目，点击右上角，选择“设置”，在“Badges”中，点击“Generate badge”