📘项目规范

企业级 Spring Boot 项目规范

1.1. 项目结构与模块化设计

• 标准构建系统结构：遵循 Maven 或 Gradle 的标准目录结构（如 src/main/java, src/main/resources, src/test/java 等）。这有助于新成员快速熟悉项目，并与构建工具和 IDE 良好集成。

• 包组织策略 ：
• 按层组织 (Layered)：将代码按技术分层，如 com.example.controller, com.example.service, com.example.repository, com.example.domain, com.example.config, com.example.dto。这是传统且常见的做法 。
• 表示层 (Presentation Layer)：包含 @RestController 或 @Controller，处理 HTTP 请求，进行参数校验、调用服务层，并返回响应。通常使用 DTO (Data Transfer Object) 与服务层交互 。
• 服务层 (Service Layer)：包含 @Service，封装核心业务逻辑、事务管理。调用仓库层进行数据操作，并可能协调多个仓库或服务 。
• 仓库/持久层 (Repository/Persistence Layer)：包含 @Repository，负责数据访问。通常使用 Spring Data JPA/JDBC/Mongo 等接口与数据库交互。定义实体 (Entity) 映射数据库表结构 。
• 领域/模型层 (Domain/Model Layer)：包含应用的核心业务对象（实体、值对象等）。
• 按功能/特性组织 (Feature-based)：将与特定功能相关的所有代码（Controller, Service, Repository, DTO, Entity 等）组织在同一个包下，如 com.example.user, com.example.order。这种方式在修改或理解某个功能时，相关代码更集中，减少了在不同层级包之间跳转的需要 。对于微服务或大型单体应用，这种方式可能更利于模块化和团队协作。
• 混合方式：也可以结合两者，顶层按功能划分模块，模块内部再按层组织。
• 选择与一致性：团队应讨论并选择一种包组织策略，并在整个项目中保持一致 。

• 配置文件分离：将配置文件（如 application.properties, logback-spring.xml）放在 src/main/resources 或特定的配置目录（如 src/main/resources/config）下，便于管理不同环境的配置 。

• 模块化 (Spring Boot Modules)：对于大型应用，可以利用 Spring Boot 的模块化能力，将应用拆分为多个子模块（Maven modules 或 Gradle subprojects）。每个模块可以有自己的职责和依赖，有助于代码复用、并行开发和按需部署 。

• SOLID 原则
• 单一职责原则 (SRP)：一个类应该只有一个引起它变化的原因。例如，用户服务 (UserService) 负责用户相关的业务逻辑，用户校验 (UserValidator) 负责用户数据校验，通知服务 (NotificationService) 负责发送通知 。这使得类更模块化，易于测试和维护。

• 依赖注入 (DI)：通过构造函数注入或 @Autowired 字段/setter 注入来管理依赖，遵循控制反转 (IoC) 原则，降低耦合度，提高可测试性 。推荐使用构造函数注入，因为它能保证依赖在对象创建时就绪，并且易于编写单元测试。

1.2. 配置管理

• 外部化配置 (Externalized Configuration) ：
• Spring Boot 允许将配置从代码中分离出来，以便在不同环境中使用相同的应用代码。支持多种外部配置源：Java 属性文件 (.properties)、YAML 文件 (.yml 或 .yaml)、环境变量、命令行参数等。
• 属性源加载顺序：Spring Boot 有一个明确的属性源加载顺序，后面的源可以覆盖前面的源。通常，命令行参数优先级最高，其次是环境变量、外部配置文件（jar 包外），然后是内部配置文件（jar 包内）。
• 配置文件位置：Spring Boot 会自动从特定位置加载 application.properties 或 application.yml 文件，包括：
1. 类路径根目录 (classpath:/)
2. 类路径下的 /config 包 (classpath:/config/)
3. 当前目录 (file:./)
4. 当前目录下的 /config/ 子目录 (file:./config/)
5. /config/ 子目录的直接子目录 。
外部配置文件（如与 jar 包同目录或在其 /config 子目录）的优先级高于内部配置文件。
• 可以使用 spring.config.name 更改默认的配置文件名 (如 myproject.properties)，使用 spring.config.location 指定额外的配置文件位置（会覆盖默认位置），或使用 spring.config.additional-location 添加额外的配置文件位置（不覆盖默认位置）。

• Profile 特定配置 (Profile-specific Configuration) 45：
• Spring Profiles 提供了一种方式来隔离应用配置的不同部分，并使其仅在特定环境中可用。
• 通过创建 application-{profile}.properties (或 .yml) 文件（如 application-dev.properties, application-prod.properties）来定义特定 profile 的配置 。
• 激活 Profile：
• 通过 JVM 系统属性：-Dspring.profiles.active=dev,hsqldb
• 通过命令行参数：--spring.profiles.active=dev,hsqldb
• 通过环境变量：SPRING_PROFILES_ACTIVE=dev,hsqldb
• 在 application.properties 中设置默认激活的 profile：spring.profiles.active=dev (但不推荐在非 profile 特定文件中设置 spring.profiles.active 来覆盖更高优先级的设置) 。
• Profile 组 (Profile Groups)：可以将多个相关的 profile 定义为一个组，通过激活组名来同时激活组内所有 profile 。例如，定义一个 production 组包含 proddb 和 prodmq。 YAML spring: profiles: group: production: proddb,prodmq
 
• spring.profiles.include：可以用来在当前激活的 profile 基础上额外激活其他 profile 。

• Spring Cloud Config ：
• 为分布式系统中的外部化配置提供服务器端和客户端支持。Config Server 提供一个中心位置来管理所有环境的应用外部属性
• 后端存储：默认使用 Git 作为后端存储，支持配置版本化和标签化。也支持其他后端如 Vault, JDBC, SVN 等 。
• Config Server：通过 @EnableConfigServer 注解轻松嵌入到 Spring Boot 应用中。提供 HTTP API 供客户端获取配置 。
• Config Client：Spring Boot 应用只需添加 spring-cloud-starter-config (或 spring-cloud-config-client) 依赖，并在 bootstrap.properties (或 bootstrap.yml) 中配置 spring.cloud.config.uri (Config Server 地址，默认为 http://localhost:8888) 和 spring.application.name (对应 Git 仓库中的配置文件名) 客户端启动时会从 Config Server 拉取配置，这些配置的优先级高于本地打包的配置文件。
• 动态刷新：结合 Spring Cloud Bus (如使用 RabbitMQ 或 Kafka)，可以实现配置变更后的动态刷新，应用无需重启即可加载新配置。

• 敏感配置处理：
• 避免在版本控制中存储明文密码或密钥。
• 可以使用 Spring Cloud Config 的加解密功能（对称或非对称加密）。
• 集成 HashiCorp Vault 等 secrets management 工具 。
• 使用环境变量或安全的外部卷挂载来注入敏感配置，尤其是在容器化环境中。

1.3. RESTful API 设计与文档

• 资源命名 (Resource Naming) ：
• 使用名词而非动词：URI 应表示资源，HTTP 方法表示对资源的操作。例如，使用 /users 而不是 /getUsers 或 /createUser。
• 使用复数名词表示集合：如 /users 表示用户集合，/users/{id} 表示特定用户。
• 层级关系：合理使用路径层级表示资源间的关系，如 /users/{userId}/orders 表示某用户的所有订单。但避免过深的层级，保持 URI 简洁。

• HTTP 方法 (HTTP Methods) ：
• GET：检索资源。应是安全的、幂等的。
• POST：创建新资源，或用于不适合其他方法的非幂等操作。服务器分配新资源的 URI。
• PUT：完整替换（更新）现有资源，或在客户端指定 URI 的情况下创建资源。应是幂等的。
• PATCH：部分更新现有资源。
• DELETE：删除资源。应是幂等的。

• HTTP 状态码 (HTTP Status Codes) ：
• 2xx (成功)：
• 200 OK：请求成功，通常用于 GET 和 PUT/PATCH 成功的响应。
• 201 Created：资源创建成功，响应头 Location 包含新资源的 URI。通常用于 POST 成功的响应。
• 202 Accepted：请求已被接受处理，但处理尚未完成（用于异步操作）。
• 204 No Content：请求成功，但响应体中无内容。通常用于 DELETE 成功的响应，或 PUT/PATCH 成功但无需返回数据的响应。
• 4xx (客户端错误)：
• 400 Bad Request：请求无效（如参数错误、格式错误、校验失败）。
• 401 Unauthorized：需要认证。
• 403 Forbidden：已认证，但无权访问该资源。
• 404 Not Found：请求的资源不存在。
• 405 Method Not Allowed：请求的 HTTP 方法不被该资源支持。
• 409 Conflict：请求冲突，如尝试创建已存在的唯一资源。
• 415 Unsupported Media Type：请求体格式不被服务器支持。
• 5xx (服务器错误)：
• 500 Internal Server Error：服务器内部发生未知错误。
• 503 Service Unavailable：服务暂时不可用（如过载或维护）。

• 数据传输对象 (DTOs) 50：
• 在 Controller 层与客户端交互以及 Service 层与 Controller 层交互时，使用 DTO 而不是直接暴露数据库实体 (Entity)。
• DTOs 有助于：
• 隐藏内部领域模型的细节。
• 根据 API 的需要定制数据结构，避免过多或过少的数据。
• 防止因领域模型变更导致 API 契约破坏。
• 处理 API 版本间的差异。
• 在 Service 层进行 Entity 到 DTO 以及 DTO 到 Entity 的转换。

• 输入校验 (Input Validation) ：
• 使用 Jakarta Bean Validation (JSR 380) 注解（如 @Valid, @NotNull, @Size, @Pattern）在 Controller 的请求体 DTO 上进行声明式校验。
• Spring Boot 会自动处理校验失败，并可以通过全局异常处理器返回统一的错误响应。

• 分页与排序 (Pagination and Sorting) ：
• 对于返回集合资源的 API，应实现分页，避免一次性返回大量数据。
• 使用查询参数如 page, size (或 limit, offset) 控制分页。
• 使用 sort 参数指定排序字段和方向（如 sort=name,asc）。
• Spring Data JPA 的 Pageable 接口与 Spring MVC 结合可以方便地实现分页和排序。

• HATEOAS (Hypertext as the Engine of Application State) ：
• 在 API 响应中包含指向相关资源和操作的链接，使客户端能够动态发现和导航 API。
• Spring HATEOAS 项目可以帮助实现此原则。

• API 版本控制 (API Versioning) ：
• 当 API 发生不兼容变更时，需要引入版本控制。常见策略：
• URI 版本控制：如 /v1/users, /v2/users。简单直观，但可能导致 URI 冗余。
• 查询参数版本控制：如 /users?version=1。
• HTTP Header 版本控制：使用自定义 Header（如 X-API-Version: 1）或 Accept Header 的参数（如 Accept: application/vnd.example.v1+json）。后者更符合 REST 风格。

• API 文档 (API Documentation) ：
• OpenAPI Specification (OAS)：一种用于描述 REST API 的标准格式（以前称为 Swagger Specification）。
• springdoc-openapi：一个与 Spring Boot 集成的库，可以根据代码（Controller、注解等）自动生成 OpenAPI 3.x 版本的文档 。
• 集成：添加 org.springdoc:springdoc-openapi-starter-webmvc-ui (for Spring MVC with Swagger UI) 或 springdoc-openapi-starter-webflux-ui (for WebFlux) 依赖 。
• 访问：默认情况下，Swagger UI 页面在 /swagger-ui.html，OpenAPI JSON 文档在 /v3/api-docs 52。路径可通过属性配置（如 springdoc.api-docs.path, springdoc.swagger-ui.path）
• 注解：可以使用 Swagger 注解（如 @Operation, @Parameter, @ApiResponse, @Schema, @SecurityRequirement）或 Javadoc 注释来丰富生成的文档 。
• @OpenAPIDefinition 和 @Info 注解用于定义 API 的全局信息（标题、版本、描述、联系人、许可证等）。
• 支持 Spring Security、Spring Data REST、Spring HATEOAS 等集成 53。

• 全局异常处理 (Global Exception Handling) ：
• 使用 @ControllerAdvice 和 @ExceptionHandler 创建全局异常处理器，将特定异常映射为统一的、对客户端友好的错误响应格式和 HTTP 状态码。

1.4. 安全性

• Spring Security ：
• Spring 生态中事实上的安全框架标准，提供全面的认证 (Authentication)、授权 (Authorization) 和常见攻击防护（如 CSRF, XSS, Clickjacking）。
• 认证：支持多种认证机制，如表单登录、HTTP Basic、OAuth2、JWT、LDAP 等 。
• JWT (JSON Web Token) 认证：适用于无状态的 REST API。
1. 用户通过凭证（用户名/密码）请求认证接口。
2. 服务器验证凭证，成功后生成一个签名的 JWT（包含用户标识、角色、过期时间等声明），返回给客户端。
3. 客户端在后续请求的 Authorization Header 中携带 JWT (通常使用 Bearer 方案)。
4. 服务器通过配置的 JWT 解码器和验证逻辑（如 Spring Security 的 OAuth2ResourceServerConfigurer）验证 JWT 的签名、过期时间等 。
5. 依赖：spring-boot-starter-oauth2-resource-server (for JWT resource server capabilities), jjwt-api, jjwt-impl, jjwt-jackson (或 jjwt-gson) for JWT creation and parsing 。
6. 配置 SecurityFilterChain，禁用 CSRF (因为 JWT 是无状态的)，设置会话管理为 STATELESS，配置 JWT 解码器 (JwtDecoder) 和编码器 (JwtEncoder)。可以使用对称密钥 (HMAC) 或非对称密钥对 (RSA) 进行签名 57。
• 授权：基于角色 (Role-based) 或权限 (Permission-based) 控制对资源的访问。
• 在 SecurityFilterChain 中使用 authorizeHttpRequests 配置 URL 访问规则，如 requestMatchers("/admin/**").hasRole("ADMIN") 或 hasAuthority("SCOPE_read") 58。
• 方法级别安全：使用 @PreAuthorize, @PostAuthorize, @Secured 等注解在 Service 方法上进行更细粒度的访问控制。

• HTTPS 强制 ：
• 生产环境必须使用 HTTPS 来加密传输中的数据。
• 在 application.properties 中配置 SSL (keystore, truststore)。
• 通过 Spring Security 配置将所有 HTTP 请求重定向到 HTTPS：
(注意： WebSecurityConfigurerAdapter 在新版本中已弃用，推荐使用基于组件的配置方式定义 SecurityFilterChain bean)。

• CSRF (Cross-Site Request Forgery) 保护 ：
• Spring Security 默认启用 CSRF 保护，对于有状态的 Web 应用（使用会话）非常重要。
• 对于无状态的 REST API (如使用 JWT)，通常可以禁用 CSRF 保护 (http.csrf(csrf -> csrf.disable())) 。

• 输入校验 (Input Validation)：除了 API 层的校验，业务逻辑层也应进行适当的校验，防止恶意输入导致安全漏洞（如 SQL 注入、XSS）。

• 依赖项漏洞扫描：定期使用工具（如 OWASP Dependency-Check, Snyk, Trivy）扫描项目依赖，及时发现并修复已知的安全漏洞。这应集成到 CI/CD pipeline 中 。

• 安全头 (Security Headers)：配置 Spring Security 添加安全相关的 HTTP 响应头，如 X-Content-Type-Options, X-XSS-Protection, Strict-Transport-Security (HSTS), Content-Security-Policy (CSP)。

• 密码管理：使用强哈希算法（如 BCrypt, SCrypt, Argon2）存储密码，Spring Security 的 PasswordEncoder 接口提供了支持 。

• 最小权限原则：为应用组件和用户分配完成其任务所需的最小权限。

• Actuator 端点安全：Actuator 暴露的端点可能包含敏感信息，需要进行保护。默认情况下，只有 /health 和 /info 端点通过 Web 暴露。可以通过 management.endpoints.web.exposure.include 和 management.endpoints.web.exposure.exclude 控制暴露哪些端点。对于敏感端点，应配置 Spring Security 进行认证和授权保护，或者将其暴露在内部网络或通过 JMX 访问 。

1.5. 测试策略

• 单元测试 (Unit Tests) ：
• 目标：独立测试最小的可测试单元（如单个方法或类），不涉及外部依赖（数据库、网络等）。
• 工具：JUnit 5 (Spring Boot Test 默认集成), Mockito (用于模拟依赖)。
• Spring Boot 支持：
• @WebMvcTest：用于测试 Spring MVC Controller 层。它只加载与 MVC 相关的配置（如 @Controller, @ControllerAdvice, WebMvcConfigurer 等），不加载完整的应用上下文。通常与 @MockBean 结合使用来模拟 Service 依赖 。
• @DataJpaTest：用于测试 JPA Repository 层。它会配置一个内存数据库（如 H2，默认）、扫描 @Entity 类、配置 Spring Data JPA 仓库。测试默认是事务性的，并在每个测试后回滚。可以注入 TestEntityManager 来准备和验证数据 62。
• @JsonTest：用于测试 JSON 序列化和反序列化 。
• 其他 Slice Test 注解：如 @DataMongoTest, @RestClientTest 等，用于测试特定应用切片 。
• 关注点：业务逻辑、边界条件、异常处理。

• 集成测试 (Integration Tests) ：
• 目标：测试多个组件（如 Controller-Service-Repository）之间的交互，或应用与外部系统（数据库、消息队列）的集成。
• 工具：@SpringBootTest (加载完整的 Spring 应用上下文), TestRestTemplate/WebTestClient (用于测试 HTTP 端点), Testcontainers (用于在 Docker 容器中启动外部依赖如数据库)。
• @SpringBootTest ：
• 可以配置 webEnvironment 属性：
• MOCK (默认)：加载 Web 应用上下文，提供一个 mock 的 Servlet 环境，不启动嵌入式服务器。可与 @AutoConfigureMockMvc 或 @AutoConfigureWebTestClient 结合使用。
• RANDOM_PORT 或 DEFINED_PORT：加载 WebServerApplicationContext，启动嵌入式服务器并监听随机或定义的端口。适用于需要真实 HTTP 请求的测试。
• 可以注入应用中的 Bean 进行测试。
• Testcontainers：允许在测试执行期间以编程方式启动和管理 Docker 容器（如 PostgreSQL, Kafka, Redis），为集成测试提供真实的环境依赖，而无需预先安装和配置这些服务。
• 关注点：组件间的契约、数据流、事务行为、与外部系统的集成。

• 端到端测试 (End-to-End / E2E Tests) ：
• 目标：从用户界面的角度测试整个应用的流程，模拟真实用户场景。
• 工具：Selenium, Cypress, Playwright (用于 Web UI 测试), Postman/RestAssured (用于 API E2E 测试)。
• 关注点：用户工作流、UI 交互、跨多个服务的完整业务流程。

• 测试覆盖率 (Test Coverage)：
• 使用 JaCoCo 等工具衡量测试覆盖率，作为代码质量的一个指标。
• 目标是达到合理的覆盖率（如 80% 以上），但更应关注测试的质量和对关键路径的覆盖，而非单纯追求数字。

• 测试数据管理：
• 为测试准备隔离的、可重复的数据。
• 使用内存数据库 (H2) 进行快速测试，或使用 Testcontainers 启动真实数据库实例。
• 使用 Flyway 或 Liquibase 管理测试数据库的 schema 和初始数据。
• 在 @DataJpaTest 中，TestEntityManager 可用于准备测试数据。

• 测试配置：
• 使用 application-test.properties (或 .yml) 为测试环境提供特定配置 。
• @TestPropertySource 注解可以覆盖或添加测试属性。
• @ActiveProfiles("test") 可以激活测试专用的 profile。

1.6. CI/CD (持续集成/持续交付) 流水线

• 核心原则："Pipeline as Code" – 将流水线定义存储在版本控制中（如 Jenkinsfile 或 .gitlab-ci.yml），使其可复现、可审计、可版本化。

• 典型阶段 (Stages) ：
1. 代码检出 (Checkout)：从版本控制系统（如 Git）拉取最新代码。
2. 编译与单元测试 (Build & Unit Test)：使用 Maven (mvn clean install 或 mvn clean verify) 或 Gradle (./gradlew build) 编译代码、运行单元测试和集成测试（部分轻量级集成测试）。生成测试报告（如 Surefire/Failsafe XML 报告）。
3. 静态代码分析 (Static Analysis)：使用 SonarQube, PMD 等工具检查代码质量、潜在 bug、代码异味和安全漏洞。
4. 安全扫描 (Security Scan)：
• 依赖项扫描：使用 OWASP Dependency-Check, Snyk 等扫描项目依赖是否存在已知漏洞 。
• 容器镜像扫描 (如果使用 Docker)：使用 Trivy, Clair 等扫描构建的 Docker 镜像是否存在操作系统或应用层漏洞 。
5. 打包 (Package)：
• 构建可执行的 JAR (或 WAR) 包：mvn package 或 gradle bootJar。
• 构建 Docker 镜像：使用 Dockerfile 和 docker build 命令，或利用 Spring Boot Maven/Gradle 插件的 build-image 目标 (基于 Buildpacks) 直接构建 OCI 镜像 。
• 将镜像推送到 Docker Registry (如 Docker Hub, Harbor, AWS ECR, Google GCR)。
6. 部署到测试/预发布环境 (Deploy to Staging/Test)：将应用部署到类生产环境进行进一步测试。
7. 端到端测试/验收测试 (E2E Test / Acceptance Test)：在测试/预发布环境运行自动化 E2E 测试。
8. 部署到生产环境 (Deploy to Production)：通过审批后，将应用部署到生产环境。可能采用蓝绿部署、金丝雀发布等策略。

• 工具：
• Jenkins：一个流行的开源自动化服务器，通过 Jenkinsfile (声明式或脚本式流水线) 定义 CI/CD 流程 。
• 需要安装相关插件（如 Git, Maven/Gradle, Docker, SonarQube Scanner, OWASP Dependency-Check Plugin）。
• 配置 JDK, Maven/Gradle 工具路径。
• 管理凭证（如 Git 仓库、Docker Registry、SonarQube token）。
• GitLab CI/CD：GitLab 内置的 CI/CD 功能，通过项目根目录下的 .gitlab-ci.yml 文件定义流水线 。
• 使用 GitLab Runners 执行作业。
• 利用 stages, jobs, script, artifacts, cache, image 等关键字定义流水线。
• GitLab 提供了许多预定义的 CI/CD 模板，包括 Maven 和 Gradle 。

• 容器化：使用 Docker 将 Spring Boot 应用及其依赖打包成标准化的容器镜像，确保环境一致性，简化部署。

• 自动化：CI/CD 的核心是自动化，减少人工干预，提高效率和可靠性。

1.7. 应用可观测性 (Observability)

• Spring Boot Actuator ：
• 提供一系列生产就绪的特性来监控和管理 Spring Boot 应用。
• 依赖：添加 spring-boot-starter-actuator 到 pom.xml 或 build.gradle。
• 端点 (Endpoints)：通过 HTTP 或 JMX 暴露信息。常见的 HTTP 端点包括：
• /actuator/health：应用健康状况。
• /actuator/info：自定义应用信息。
• /actuator/metrics：应用指标。
• /actuator/prometheus：Prometheus 格式的指标 (需添加 micrometer-registry-prometheus 依赖)。
• /actuator/loggers：查看和修改日志级别。
• /actuator/httpexchanges (以前是 /actuator/httptrace)：HTTP 请求追踪信息。
• /actuator/threaddump：线程转储。
• /actuator/heapdump：堆转储。
• 暴露端点：默认情况下，出于安全考虑，只有 /health 和 /info 通过 HTTP 暴露。需通过 management.endpoints.web.exposure.include (如 health,info,metrics,prometheus) 和 management.endpoints.web.exposure.exclude 属性配置哪些端点通过 Web 暴露 。
• 管理端口：可以将 Actuator 端点暴露在与应用主服务不同的管理端口上，通过 management.server.port 配置 。
• 自定义端点：可以使用 @Endpoint, @ReadOperation, @WriteOperation, @DeleteOperation 注解创建自定义 Actuator 端点，以暴露应用特定的管理信息或操作 。

• Metrics (指标) with Micrometer and Prometheus ：
• Micrometer：一个应用指标外观 (facade)，与 Spring Boot 深度集成。它提供了一个厂商中立的 API 来收集应用指标，并支持将指标导出到多种监控系统 。
• 核心概念：MeterRegistry (指标注册表), Meter (指标接口，如 Counter, Gauge, Timer, DistributionSummary) 。
• Spring Boot 自动配置一个组合的 MeterRegistry (CompositeMeterRegistry)，并为类路径上找到的每个受支持的监控系统实现添加一个注册表。
• Prometheus 集成：
1. 添加依赖：io.micrometer:micrometer-registry-prometheus 。
2. 暴露 Prometheus 端点：在 application.properties 中设置 management.endpoints.web.exposure.include=prometheus (以及 management.endpoint.prometheus.enabled=true，通常默认启用) 。
3. Prometheus 服务器配置一个抓取作业 (scrape job) 来定期从应用的 /actuator/prometheus 端点拉取指标。
• 常见自动配置指标：JVM 指标 (内存、GC、线程)、CPU 指标、HTTP 服务器请求指标、Tomcat 指标、Logback 日志事件计数器、数据源连接池指标 (HikariCP 等) 等 。
• 自定义指标：
• 通过注入 MeterRegistry 并使用其 API 编程式创建和注册自定义指标。
• 使用 Micrometer 的注解，如 @Timed (测量方法执行时间), @Counted (计数方法调用) 。
• 直方图与百分位数：可以通过 management.metrics.distribution.percentiles-histogram.<meter-name>=true 开启特定指标的直方图数据，用于计算百分位数（如 P95, P99 延迟）38。注意这会增加指标的基数 (cardinality)。

• Distributed Tracing (分布式追踪) with OpenTelemetry (OTel) ：
• OpenTelemetry：CNCF (Cloud Native Computing Foundation) 的一个开源可观测性框架，旨在标准化遥测数据（追踪、指标、日志）的生成、收集和导出。它是语言无关的，支持多种后端 。
• Spring Boot 3+ 与 Micrometer Tracing：Spring Boot 3 引入了 Micrometer Tracing，这是一个新的抽象层，类似于 Micrometer Metrics。它可以对接不同的追踪库作为后端，如 OpenTelemetry 或 Brave (Zipkin 的追踪库)。这取代了之前 Spring Cloud Sleuth 的功能 。
• 核心概念：
• Trace (追踪)：代表一个请求在分布式系统中的完整路径，由一个唯一的 Trace ID 标识。
• Span (跨度)：Trace 中的一个基本工作单元，代表一个特定的操作（如一次 HTTP 调用、一次数据库查询、一个方法执行）。每个 Span 有一个 Span ID，并可以有父 Span ID 来构建调用链。Span 包含操作名称、开始/结束时间戳、属性 (tags/attributes) 和事件 (logs) 。
• Context Propagation (上下文传播)：Trace ID 和 Span ID 等追踪上下文信息需要在服务调用间（如通过 HTTP Header）进行传播，以连接各个 Span 形成完整的 Trace 。W3C Trace Context 是一种标准化的传播格式。
• 集成 OpenTelemetry：
1. 依赖：
• 如果直接使用 OpenTelemetry Java Agent：无需修改代码，通过 JVM 参数 -javaagent:path/to/opentelemetry-javaagent.jar 启动应用 。
• 如果使用 Spring Boot 自动配置 (Micrometer Tracing with OTel backend)：
• 添加 micrometer-tracing-bridge-otel (或 micrometer-tracing-bridge-brave 如果用 Brave)。
• 添加 OTLP (OpenTelemetry Protocol) 导出器依赖，如 opentelemetry-exporter-otlp，用于将追踪数据发送到兼容 OTLP 的后端 77。
• 可能还需要特定场景的检测库，如 opentelemetry-instrumentation-jdbc (如果 Micrometer Tracing 的自动配置不够用) 。
2. 配置 (application.properties 或 .yml) ：
• otel.service.name (或 spring.application.name 会被用作默认服务名)。
• otel.traces.exporter=otlp (或 management.tracing.exporter.zipkin.endpoint 如果用 Zipkin)。
• otel.exporter.otlp.endpoint=<collector-or-backend-url> (如 Jaeger, Tempo, Uptrace 的 OTLP ingest 地址，通常是 http://localhost:4317 或 http://localhost:4318/v1/traces)。
• management.tracing.sampling.probability=1.0 (在开发环境中设置为 1.0 以采集所有追踪，生产环境可适当调低以减少开销)。
3. 自动检测 (Auto-instrumentation)：Spring Boot 和 Micrometer Tracing (结合 OTel/Brave) 会自动检测许多常见的框架和库，如 Spring MVC (Controller 调用), WebClient/RestTemplate (出站 HTTP 调用), JDBC, Kafka, RabbitMQ 等，并自动创建 Span。
4. 手动检测 (Manual Instrumentation)：
• 使用 Micrometer Tracing 的 @NewSpan 和 @ContinueSpan 注解在方法上创建新的 Span 或继续现有的 Span 71
• 通过注入 Tracer (Micrometer Tracing API) 或 io.opentelemetry.api.trace.Tracer (OTel API) 以编程方式创建和管理 Span，添加自定义属性和事件。
• 追踪后端 (Tracing Backends)：收集、存储和可视化追踪数据的系统，如 Jaeger , Zipkin , Grafana Tempo , Uptrace , New Relic, Datadog 等。

• Logging (日志) with Correlation and Centralization：
• 关联日志与追踪：在日志中包含 traceId 和 spanId 是实现可观测性的关键。当发生错误或需要分析特定请求时，可以通过这些 ID 在日志系统和追踪系统中找到所有相关的记录 。
• 配置 Logback (或 Log4j2) 的日志模式 (pattern) 以包含 traceId 和 spanId。Micrometer Tracing 会自动将它们放入 MDC 中。例如，在 logback-spring.xml 中使用 %X{traceId} 和 %X{spanId} 。
• 集中式日志系统：
• ELK Stack (Elasticsearch, Logstash, Kibana)：如前述 。
• Grafana Loki：一个为 Prometheus 设计的、水平可扩展、高可用、多租户的日志聚合系统。它不索引日志内容，而是像 Prometheus 一样只索引关于日志流的元数据标签 (labels)，因此存储成本较低，且与 Grafana 紧密集成 。
• 使用 loki-logback-appender (或 loki4j) 将 Spring Boot 应用的 Logback 日志直接发送到 Loki 。
• 在 logback-spring.xml 中配置 Loki appender，指定 Loki URL 和标签（如应用名、主机名）。

• 可视化与告警 (Visualization and Alerting)：
• Grafana：一个非常流行的开源分析和监控平台，可以连接多种数据源（Prometheus, Loki, Tempo, Elasticsearch, Jaeger, Zipkin 等），创建统一的仪表盘来展示指标、日志和追踪数据 。
• 告警：基于指标（如错误率、延迟、资源使用率）或日志模式设置告警规则，当系统出现异常时及时通知相关人员。Prometheus Alertmanager, Grafana Alerting, ElastAlert (for ELK) 等工具可用于此目的。