QuickBlue 微服务开发手册

版本: 1.1 最后更新: 2026年6月27日 适用对象: 初级开发者、中级开发者、测试工程师

目录

• 1. 开发环境准备

• 2. 项目结构说明

• 3. 快速启动指南

• 4. 微服务开发规范

• 5. 分布式链路追踪使用指南

• 6. 数据库操作指南

• 7. API 开发指南

• 8. 前端开发指南

• 9. 测试指南

• 10. 部署指南

  • 10.1 Docker 部署

  • 10.2 Nacos 配置一键同步

  • 10.3 配置模板维护规范

• 11. 常见问题解答

1. 开发环境准备

1.1 必备软件

1.2 环境变量配置

# Windows PowerShell
$env:JAVA_HOME="C:\Program Files\Java\jdk-17"
$env:MAVEN_HOME="C:\apache-maven-3.8.6"
$env:PATH="$env:JAVA_HOME\bin;$env:MAVEN_HOME\bin;$env:PATH"

2. 项目结构说明

xxxxxxxxxx
QuickBlue-parent-pg/
├── QuickBlue-parent-pg/          # 父POM，统一依赖管理
├── QuickBlue-admin/              # 管理后台（Spring Boot Admin）
├── QuickBlue-gateway/            # API网关服务
├── QuickBlue-modules/           # 业务模块
│   ├── QuickBlue-system/         # 系统管理服务
│   ├── QuickBlue-business/       # 业务服务
│   ├── QuickBlue-ai/             # AI智能体服务
│   └── QuickBlue-support/        # 支撑服务
├── QuickBlue-common/             # 公共模块
│   ├── QuickBlue-common-core/    # 核心工具类
│   ├── QuickBlue-common-web/     # Web相关（含链路追踪）
│   ├── QuickBlue-common-database/# 数据库相关
│   └── ...                       # 其他公共模块
├── database/postgresql/          # 数据库脚本
├── nacos_config/                 # Nacos配置中心配置
├── doc/                          # 文档目录
└── uploads/                      # 文件上传目录

3. 快速启动指南

3.1 启动依赖服务

​x
# 启动 PostgreSQL（已预配置）
# 启动 Redis（已预配置）

# 启动 Zipkin 追踪服务
docker run -d -p 9411:9411 --name zipkin openzipkin/zipkin

# 启动 Nacos 配置中心
# 使用 nacos_config 目录下的配置文件

3.2 启动微服务

xxxxxxxxxx
# 1. 构建项目
cd QuickBlue-parent-pg
mvn clean package -DskipTests

# 2. 启动各服务（按顺序）
# 启动 Nacos（如果未启动）
# 启动 Gateway
cd QuickBlue-gateway && mvn spring-boot:run

# 启动 System 服务
cd QuickBlue-modules/QuickBlue-system && mvn spring-boot:run

# 启动 Business 服务
cd QuickBlue-modules/QuickBlue-business && mvn spring-boot:run

3.3 访问服务

4. 微服务开发规范

4.1 包命名规范

xxxxxxxxxx
com.budaos.[module].[layer].[package]
# 示例：
com.budaos.system.controller      # 控制器层
com.budaos.system.service         # 服务层
com.budaos.system.mapper          # Mapper层
com.budaos.system.domain          # 实体类
com.budaos.system.dto             # DTO对象
com.budaos.system.vo              # VO对象

4.2 代码风格

• ✅ 使用 Lombok 简化代码（@Data, @Builder, @Slf4j）

• ✅ 统一异常处理（GlobalExceptionHandler）

• ✅ 接口返回统一格式（ResponseDTO）

• ✅ 日志记录规范（使用 SLF4J + Logback）

5. 分布式链路追踪使用指南

5.1 配置说明

Nacos 配置（common-config.yaml）

xxxxxxxxxx
management:
  tracing:
    sampling:
      probability: ${TRACING_SAMPLE_RATE:0.0}  # 采样率: 0.0-1.0
  zipkin:
    tracing:
      endpoint: ${ZIPKIN_ENDPOINT:http://localhost:9411/api/v2/spans}

环境变量设置

5.2 使用方法

基本使用（零配置）

• ✅ 所有 HTTP 请求自动追踪

• ✅ Trace ID 自动传播（X-B3-TraceId 头部）

• ✅ 日志自动包含 Trace ID 和 Span ID

自定义 Span 标签

xxxxxxxxxx
@Service
public class UserService {
    
    @Traced(value = "user-service.find-by-id", extraTags = {
        @Tag(key = "user.id", value = "#id"),
        @Tag(key = "user.type", value = "'normal'")
    })
    public User findById(Long id) {
        return userMapper.selectById(id);
    }
}

异步任务追踪

xxxxxxxxxx
@Service
public class AsyncService {
    
    @Async
    @Traced("async.task.process")
    public void processAsyncTask(String taskId) {
        // 异步处理逻辑
        log.info("Processing async task: {}", taskId);
    }
}

5.3 验证追踪效果

1. 查看日志: 检查控制台日志是否包含 [traceId] 和 [spanId]

2. 调用接口: 发起一个跨服务的请求

3. 访问 Zipkin: http://localhost:9411 查看调用链路

4. 搜索 Trace: 在 Zipkin UI 中搜索 Trace ID

6. 数据库操作指南

6.1 PostgreSQL 适配要点

Boolean 类型处理

• ✅ 使用 SmallintBooleanTypeHandler 处理 smallint 类型的布尔字段

• ✅ 配置在 MybatisPlusConfig.java 中

• ✅ 不需要修改 SQL，自动类型转换

分页查询

xxxxxxxxxx
// 使用 MyBatis Plus 分页
Page<User> page = new Page<>(1, 10); // 第1页，每页10条
Page<User> result = userMapper.selectPage(page, wrapper);

6.2 数据库脚本管理

7. API 开发指南

7.1 RESTful API 规范

7.2 统一响应格式

xxxxxxxxxx
{
  "code": 200,
  "message": "操作成功",
  "data": { /* 返回数据 */ },
  "timestamp": "2026-05-01T10:30:45.123"
}

7.3 异常处理

• ✅ 全局异常处理器（GlobalExceptionHandler）

• ✅ 统一错误码管理（ErrorCode 枚举）

• ✅ 业务异常自动转换为标准响应

8. 前端开发指南

8.1 项目结构

xxxxxxxxxx
QuickBule-admin-webpg/
├── src/
│   ├── api/          # 接口请求封装
│   ├── views/        # 页面组件
│   ├── components/   # 可复用组件
│   ├── store/        # Pinia 状态管理
│   ├── router/       # 路由配置
│   └── utils/        # 工具函数

8.2 API 调用示例

xxxxxxxxxx
// src/api/system/user.js
import request from '@/utils/request'

export function getUserList(params) {
  return request({
    url: '/system/user/list',
    method: 'get',
    params
  })
}

// 在组件中使用
const { data } = await getUserList({ page: 1, size: 10 })

9. 测试指南

9.1 单元测试

xxxxxxxxxx
@SpringBootTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
class UserServiceTest {
    
    @Autowired
    private UserService userService;
    
    @Test
    void testFindById() {
        User user = userService.findById(1L);
        assertNotNull(user);
        assertEquals("admin", user.getUsername());
    }
}

9.2 接口测试

• ✅ 使用 Knife4j 文档进行手动测试

• ✅ 使用 Postman 导入 Swagger JSON 进行自动化测试

• ✅ 使用 JMeter 进行压力测试

10. 部署指南

10.1 Docker 部署

xxxxxxxxxx
# QuickBlue-gateway/Dockerfile
FROM openjdk:17-jre-slim
COPY target/QuickBlue-gateway.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java","-jar","/app.jar"]

10.2 Nacos 配置一键同步

背景: 项目根目录 nacos_config/ 存放了所有服务的 Nacos 配置模板（common 公共配置 + services 服务私有配置）。以往每次改完模板需要手动打开 Nacos 控制台逐条粘贴发布，容易出错。现已内置「一键同步」功能，在管理后台点击按钮即可将本地模板批量推送到 Nacos。

架构

xxxxxxxxxx
nacos_config/                       ← 👈 唯一数据源（你只改这里）
├── common/         公共配置
│   ├── common-config.yaml
│   ├── postgresql-common.yaml
│   ├── redis-common.yaml
│   ├── sa-token-common.yaml
│   └── level3-protect-common.yaml
└── services/       服务私有配置
    ├── QuickBlue-gateway.yaml
    ├── QuickBlue-system-pg.yaml
    ├── QuickBlue-business-pg.yaml
    ├── QuickBlue-support-pg.yaml
    ├── QuickBlue-ai-pg.yaml
    └── QuickBlue-admin.yaml

        │  Maven 编译时
        │  maven-resources-plugin 自动复制
        ▼

target/classes/nacos_config_templates/   ← 运行时 classpath（自动生成）

        │  管理后台 → Nacos配置管理 → 点击「一键同步」
        ▼

Nacos 服务器  ←  配置发布到 Nacos，同名配置自动更新

使用方法

1. 修改配置模板：编辑 nacos_config/common/ 或 nacos_config/services/ 下的 .yaml 文件

2. 编译项目：mvn compile -pl QuickBlue-modules/QuickBlue-support（IDE 自动编译也可）

3. 启动 support 服务：确保 support 服务正常运行

4. 打开管理后台：进入 系统管理 → Nacos配置管理

5. 选择命名空间：在下拉框中选择目标命名空间（如 QuickBlue-dev）

6. 点击「一键同步」：

   • 系统自动扫描 classpath 下的所有配置模板

   • 逐文件对比 Nacos 上已有内容：

     • 内容无变化 → 跳过（不会重复写入）

     • 已存在但内容不同 → 更新（覆盖）

     • 新配置 → 创建（首次发布）

7. 查看结果：弹窗显示同步汇总（共扫描 N 个文件，成功/跳过/失败各多少）

关键设计

10.3 配置模板维护规范

修改规范

1. 唯一数据源：始终编辑项目根 nacos_config/ 下的文件，不要修改 support/src/main/resources/nacos_config_templates/（那是编译自动生成的回退副本）

2. 分组规则：

   • common/ → Nacos group QuickBlue_GROUP，公共配置供所有服务共享读取

   • services/ → Nacos group QuickBlue_GROUP，文件名去掉 -pg 后缀作为 dataId

3. 新增配置文件后：需要重新编译 support 模块才会被一键同步扫描到

4. 占位符规范：使用 ${ENV_VAR:default} 格式，环境变量通过部署配置注入

同步时机

11. 常见问题解答

Q1: 链路追踪不生效？

A: 检查以下几点：

• ✅ micrometer-tracing-starter-brave 依赖是否正确引入

• ✅ TRACING_SAMPLE_RATE 环境变量是否设置为大于 0 的值

• ✅ ZIPKIN_ENDPOINT 是否正确配置

• ✅ Zipkin 服务是否正常运行

Q2: 日志中没有 Trace ID？

A: 检查 logback-spring.xml 是否存在且配置正确，确保使用了 %X{traceId:-} 格式。

Q3: 如何禁用链路追踪？

A: 设置 TRACING_SAMPLE_RATE=0.0 或在配置中设置 management.tracing.sampling.probability=0.0

Q4: 如何自定义 Trace ID 生成？

A: 创建自定义 TracerCustomizer Bean，重写 customize 方法。

技术支持: 如遇问题，请联系架构支持团队或查阅 doc/ 目录下的相关文档。