micro-java 架构与请求链路

整体拓扑

                         contracts/openapi + schema.sql
                                    │
                                    ▼
              ┌─────────────────────────────────────────────┐
              │           gateway (:8080)                   │
              │  Spring Cloud Gateway + Resilience4j        │
              │  路由 /api/v1/auth/** → auth-service        │
              │       /api/v1/system/** → system-service    │
              └──────────────┬──────────────┬───────────────┘
                             │              │
                    Nacos 服务发现          │
                             │              │
              ┌──────────────▼──┐    ┌──────▼──────────────┐
              │ auth-service    │    │ system-service       │
              │ (:8081)         │    │ (:8082)              │
              │ 登录/Token/me   │    │ RBAC CRUD            │
              │ 直连 MySQL      │    │ ShardingSphere-JDBC  │
              └────────┬────────┘    │ Seata / RabbitMQ     │
                       │             └──────────┬───────────┘
                       │                        │
                       └────────────┬───────────┘
                                    ▼
                              MySQL (:3306)

模块职责

xichen-common

共享基础设施，被 auth-service 与 system-service 通过 @Import 引入：

包路径	职责
common.config.SecurityConfig	JWT 过滤器、白名单、CORS、@EnableMethodSecurity
common.security.*	JwtTokenProvider、401/403 JSON 处理器
common.response.*	ApiResponse、PageResult
common.exception.*	BusinessException、GlobalExceptionHandler

xichen-domain

实体、Mapper、DTO，auth 与 system 共用数据模型，避免跨服务重复定义。

auth-service

• 路径前缀：/api/v1/auth/*、/api/v1/health
• 直连 spring.datasource（MySQL）
• 注册到 Nacos，服务名 auth-service
• 不包含 system CRUD；登录时查用户、角色、权限、菜单树

system-service

• 路径前缀：/api/v1/system/*
• 数据源：ShardingSphereDataSourceConfig（当前等价单库，预留分库分表）
• DataSeeder：首次启动写入 admin 账号、权限、菜单
• 创建用户时发布 UserCreatedEvent（RabbitMQ 或 Kafka）
• assignRoles 使用 @GlobalTransactional（Seata 分布式事务演示）

gateway

• 对外端口 8080，与 server-java 一致
• lb://auth-service / lb://system-service 负载均衡（依赖 Nacos）
• 默认过滤器：GET 重试、熔断；失败时 forward:/fallback 返回 503 JSON
• 不做 JWT 校验（由各业务服务 xichen-common 完成）

前端登录时序（经网关）

sequenceDiagram
    participant F as admin 前端
    participant G as gateway :8080
    participant A as auth-service
    participant S as system-service
    participant DB as MySQL

    F->>G: POST /api/v1/auth/login
    G->>A: 转发（Nacos 发现）
    A->>DB: 校验用户、查角色权限菜单
    A-->>G: accessToken + menus
    G-->>F: LoginResponse

    F->>G: GET /api/v1/system/users (Bearer)
    G->>S: 转发
    S->>S: JWT 校验 + @PreAuthorize
    S->>DB: 分页查询
    S-->>F: PageResult

网关路由表

路由 id	路径	目标服务
auth-service	/api/v1/auth/**、/api/v1/health	lb://auth-service
system-service	/api/v1/system/**	lb://system-service
auth-swagger	/auth-service/swagger-ui/** 等	auth-service（StripPrefix=1）
system-swagger	/system-service/swagger-ui/** 等	system-service（StripPrefix=1）

默认端口

组件	端口	环境变量
gateway	8080	SERVER_PORT
auth-service	8081	SERVER_PORT
system-service	8082	SERVER_PORT
Nacos	8848	NACOS_ADDR
RabbitMQ	5672	RABBITMQ_HOST
Seata Server	8091	SEATA_SERVER
Kafka	9092	KAFKA_BOOTSTRAP

与 Monorepo 的关系

• 不纳入 Turbo build pipeline（Maven 独立构建）
• pnpm 仅用于 dev / build 脚本包装 mvn spring-boot:run / mvn package
• 改 xichen-common 或 xichen-domain 后须先 mvn install -DskipTests

相关文档

• 概览
• 本地启动
• 中间件
• RBAC 请求链路（前端视角）