Samples 模块说明

模块总览

端口用于 IDE 本地运行。完整容器模式只对宿主机发布 Gateway 和 Admin，其余后端通过容器网络访问。

Parent：统一构建

macula-samples-parent/pom.xml 维护后端公共依赖、插件及 local/dev/stg/pet/prd profile，使用 profile.active 将构建环境传给资源配置。模块内按需声明 Starter，公共版本由 Parent / Macula Boot 管理。

Parent 是构建模块，没有 application.yml，也不启动 Web 服务。前端依赖由 Admin 的 package.json 与锁文件管理。

API：服务间契约

macula-samples-api 是聚合 POM，包含 macula-samples-basic-api、macula-samples-service1-api。

• api/：Feign 接口及调用契约。
• form/、query/：请求表单与查询条件。
• vo/、errors/：返回模型和服务错误约定。

例如 ApplicationFeignClient 的服务名为 macula-samples-service1，声明 /api/v1/app 等接口。调用方引用 API 制品，不依赖 Service1 的实现包；实体、Mapper 与业务实现留在业务服务中。

API 模块不启动应用，也不配置 JWK 或运行时可观测性导出。

Gateway：统一入口

macula-samples-gateway 使用 Spring Cloud Gateway。当前路由在 application.yml 的 spring.cloud.gateway.server.webflux.routes 下定义：

网关通过 IAM 的 introspection 地址验证客户端 Token，再将内部 JWT 传给后端。下游从本应用网关的 /oauth2/jwks 获取验证公钥。

Gateway 同时连接项目 Redis 与 Cloud System Redis。当前源码的 RedisConfiguration 显式绑定 spring.redis.* 和 spring.redis.system.*，这是 Samples 网关自定义的配置契约，不能直接改成业务服务的 Redis 前缀。

Admin BFF：面向管理端的聚合

macula-samples-admin-bff 面向 Admin 组织接口，ApplicationController → ApplicationService → ApplicationFeignClient 将应用管理请求转给 Service1。

BFF 引入 System Starter，通过 macula.cloud.endpoint、app-key、secret-key 访问 Cloud System，提供用户与菜单能力。endpoint 指向 Macula Cloud Gateway，不指向 Samples Gateway。

同时，BFF 作为资源服务器配置 Samples Gateway 的 spring.security.oauth2.resourceserver.jwt.jwk-set-uri。这两个地址服务于不同方向，不能互换。

管理端用户信息的典型路径为：浏览器 /api/admin/api/v1/users/me → Vite / Nginx 去掉 /api → Gateway 去掉 /admin → BFF /api/v1/users/me。

BFF 与业务服务还通过 Security Starter 使用 @PreAuthorize、@PostAuthorize、@CheckOwner 做操作与数据级授权。整体分层见安全架构，具体用法见 Security。

Service1：业务与持久化

macula-samples-service1 的已提交主线示例是应用管理：

controller/ApplicationController
service/ApplicationService → service/impl/ApplicationServiceImpl
converter/ApplicationConverter
mapper/ApplicationMapper
pojo/bo/ApplicationBO、pojo/entity/Application
resources/db/migration/V1__baseline.sql

Controller 接收请求，Service 组织业务和事务，Mapper 处理数据访问，Converter 负责不同层的对象转换。接口表单、查询和返回模型由 Service1 API 契约模块共享。

该模块使用 MyBatis-Plus、Redis、Flyway 及网关 JWT 校验。新增业务的完整步骤见开发业务服务。

Basic：公共服务边界

macula-samples-basic 是可部署的公共服务模块。当前单仓主线提供启动类和运行配置骨架，具体公共能力按项目需要实现；通用框架能力继续复用 Macula Boot。

需要跨服务复用的接口可放入 Basic API。该模块使用应用网关的 JWK 地址，不承担 IAM 登录或全局系统管理。

OpenAPI：对外接口边界

macula-samples-openapi 用于组织面向外部调用方的 API，Gateway 已预留 /openapi/** 路由。当前单仓主线提供运行骨架，业务接口需要按实际需求实现。

接口的数据模型、版本、返回结构与内部业务解耦；调用内部服务时使用其 API 契约。OpenAPI 同样作为资源服务器校验应用网关签发的 JWT。

Thirdparty：第三方防腐层

macula-samples-thirdparty 用于隔离第三方协议与内部业务模型，目前也是运行骨架。后续可将外部 SDK、请求签名、响应转换和外部错误处理收敛在这一边界，向内部提供稳定契约。

第三方凭据由运行环境或配置中心提供；来自内部的受保护请求仍使用应用网关 JWT。不要将外部平台返回模型直接扩散到各业务服务。

Admin：浏览器管理端

macula-samples-admin 基于 Vue 3、Vite、Pinia、Vue Router 与 Element Plus，独立安装和构建。业务、用户、菜单请求走同源 /api；登录 Token 来自外部 Macula Cloud IAM。

• 本地 Vite 默认代理到 http://127.0.0.1:6000，去掉 /api 后交给 Samples Gateway。
• IAM 地址需要能被浏览器访问；容器内部地址不能写入浏览器配置。
• Admin 根 .env 保存公共本地值，mode 文件覆盖差异，Vite 再读取仓库根目录的 deploy/.env。
• Docker 由运行时 config.js 提供配置；IDE 开发模式不使用该文件。

前端不是 JWT 资源服务器，不配置后端的 jwk-set-uri。OAuth 登记与 IAM 的 Origin 设置应与实际页面地址一致。

配置与源码

各模块的 application.yml 分层、地址及变量规范统一见配置规范。源码按上述模块名位于 macula-samples 单仓项目的目录中。前端与后端共用仓库版本，构建和运行职责按模块划分。

• ←上一篇
• 下一篇→