开发指引 on Macula

开发环境准备

Mon, 01 Jan 0001 00:00:00 +0000

工具与平台

项目	用途
Java 17、Maven	编译后端，版本与 Macula Boot Parent 保持一致
Node.js 22、npm	当前 Samples Admin 的 Dockerfile 使用 Node 22；按 package-lock.json 安装依赖
Docker Compose v2	启动本地中间件或完整应用容器
Macula Cloud	已运行的 Gateway、IAM、System，提供登录、菜单、用户与权限能力

Samples 不重复部署认证中心和系统管理。开始前，在 Macula Cloud 中登记 macula-samples-admin-bff 应用及管理端使用的 OAuth Client。

获取源码

git clone https://github.com/macula-projects/macula-samples.git
cd macula-samples

单个仓库包含后端模块、Admin 前端和部署目录。将根 pom.xml 导入 IDE，即可加载全部后端 Maven 模块；Admin 在自己的目录安装前端依赖。

也支持多仓模式，各模块可在独立仓库中维护，通过工作区统一组织，参考 macula-samples-workspace。本章后续步骤以单仓项目为准。

本地连接准备

Samples 的默认宿主机端口与 Macula Cloud 分开：MySQL 23306、Redis 26379、Nacos 28848、Samples Gateway 6000、Samples Admin 5800。

在 deploy/.env 中维护 Compose / Vite 使用的本地环境值。IDE 启动 Java 服务时使用 local profile，需覆盖的值在 IDE 环境变量中显式设置，Java 不会自动读取该 .env 文件。

获取与组织 Samples 项目

Mon, 01 Jan 0001 00:00:00 +0000

单仓项目结构

Macula Samples 将后端、前端和部署配置放在同一 Git 仓库中。根 pom.xml 聚合八个后端模块，deploy/ 统一维护本地编排；Admin 前端在自身目录构建，不属于 Maven 聚合模块。

macula-samples/
├── pom.xml
├── deploy/
├── macula-samples-parent/
├── macula-samples-api/
├── macula-samples-gateway/
├── macula-samples-admin-bff/
├── macula-samples-service1/
├── macula-samples-basic/
├── macula-samples-openapi/
├── macula-samples-thirdparty/
└── macula-samples-admin/

应用内的依赖关系

Parent 统一后端依赖、插件与环境 profile，运行模块继承该 Parent。
API 聚合 Basic API 和 Service1 API，放置可被其他服务引用的接口契约。
BFF 依赖 Service1 API，通过 Feign 调用 Service1；业务实现留在 Service1 中。
Gateway 路由到 BFF / OpenAPI，Admin 通过同源 /api 访问 Gateway。
Basic、Thirdparty 与 OpenAPI 是不同职责的运行模块，按实际业务扩展。

完整说明见模块说明。API 与 Parent 不作为独立的 Spring Boot 服务启动。

Samples 模块说明

Mon, 01 Jan 0001 00:00:00 +0000

模块总览

模块	职责	默认本地端口
Parent	后端依赖、插件、构建 profile	—
API	Basic / Service1 的服务间契约	—
Gateway	路由、IAM Token 验证、内部 JWT 转换	6000
Admin BFF	管理端接口聚合与 Macula Cloud 接入	6001
OpenAPI	面向外部调用方的接口聚合边界	6002
Service1	业务实现、数据访问与数据库迁移	6003
Basic	可独立部署的公共服务边界	6004
Thirdparty	对第三方协议和模型的封装边界	6005
Admin	Vue 管理端	5800

端口用于 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 与锁文件管理。

application.yml 配置规范

Mon, 01 Jan 0001 00:00:00 +0000

配置入口与职责

Samples 的后端统一使用 src/main/resources/application.yml，按 YAML 多文档和 profile 分层。公共约定放在公共段，本地连接值放在 local，容器网络差异放在 docker；dev/stg/pet/prd 保留配置中心连接信息，业务配置由 Nacos 提供。

配置范围	放置内容
公共段	应用名、端口占位、profile group、配置导入、路由 / 组件结构
local	IDE 可用的本机地址、开发端口和本地开关
docker	容器 DNS、容器端口以及与 local 不同的值
dev / stg / pet / prd	对应环境的 Nacos 连接；其余环境值通过 Data ID 管理

共享的模块版本由 Parent 管理，application.yml 只承载运行配置。地址和凭据使用环境变量 / 配置中心提供的值。

公共段与配置导入

以下是以 Service1 为例的配置骨架；完整字段以相应模块源码为准：

server:
 port: ${SERVER_PORT:6003}
spring:
 application:
 name: macula-samples-service1
 profiles:
 active: '@profile.active@'
 group:
 docker: local
 config:
 import:
 - optional:nacos:${spring.application.name}.yml?refreshEnabled=true
 - optional:nacos:${spring.application.name}-${spring.profiles.active}.yml?refreshEnabled=true
 cloud:
 nacos:
 server-addr: ${spring.config.nacos.server-addr}
 namespace: ${spring.config.nacos.namespace}
 username: ${spring.config.nacos.username}
 password: ${spring.config.nacos.password}
 discovery:
 namespace: ${spring.cloud.nacos.namespace}

@profile.active@ 由 Maven profile 在构建时替换；local/dev/stg/pet/prd 定义在 Samples Parent。运行时可通过 SPRING_PROFILES_ACTIVE 选择环境，完整容器使用 docker，并通过 profile group 叠加 local。

部署Macula平台

Mon, 01 Jan 0001 00:00:00 +0000

代码与运行方式

Macula Cloud 后端和管理端共用一个仓库，管理端位于 macula-cloud-admin/。本页根据当前仓库的本地部署说明整理；完整配置、端口与排错步骤见部署 README。

git clone https://github.com/macula-projects/macula-cloud.git
cd macula-cloud
cp deploy/.env.example deploy/.env

按本机环境修改 deploy/.env。开发编排用于本地开发与集成验证；共享或生产环境需要另行配置凭据、证书、备份和高可用。

方式一：IDE 调试

先启动中间件和初始化任务：

./deploy/scripts/compose.sh config
./deploy/scripts/compose.sh up
./deploy/scripts/compose.sh status

后端需要 Java 17 与 Maven。按部署 README 完成数据库迁移和 IDE 启动配置，再启动 IAM、Gateway、System 等所需服务。

管理端使用推荐的 Node.js 24 LTS，在同一仓库内运行：

cd macula-cloud-admin
npm ci
npm run dev

方式二：完整容器

使用 Docker Compose v2，并在 deploy/.env 中提供当前部署说明要求的配置，再启用 apps profile：

./deploy/scripts/compose.sh config-apps
./deploy/scripts/compose.sh up-apps
./deploy/scripts/compose.sh status

该模式包含后端应用与 Admin。默认管理端地址为 http://127.0.0.1:5900/，可通过环境配置调整端口。

配置与更新

后端使用 application.yml 和环境 profile；共享环境的配置按当前 Data ID 规则放入 Nacos。数据库使用 Flyway 管理，启动顺序、服务地址和持久化卷处理以部署 README 为准。

以 Service1 开发业务服务

Mon, 01 Jan 0001 00:00:00 +0000

从一个完整调用链开始

当前已提交的 Service1 示例提供应用管理接口，可按以下链路阅读：

Admin → Gateway → Admin BFF → ApplicationFeignClient → Service1 → Mapper / 数据库

本页以该主线代码说明新增业务的方法；应用接入与环境字段见配置规范。

应用分层规范

Samples 以 Controller → Service → Mapper 为业务服务的基本调用方向。先明确每层职责，再新增接口和模型；完整规范见后端开发规范 → 应用分层。

Controller：接收 HTTP 请求、校验参数并调用 Service，返回业务对象，由 Web Starter 统一包装响应；不直接操作 Mapper、不吞异常。
Service：实现业务规则、授权与事务边界，需要原子性的写操作在公开业务方法上声明事务。
Mapper：执行数据访问，查询时落实用户、租户和数据范围，使用参数绑定。
Converter：使用 MapStruct 转换各层模型，避免在 Controller 中堆叠字段复制。

模型沿用 Query（查询条件）、Form（写入表单）、DTO（传输）、VO（展示结果）、BO（组合业务对象）、Entity（表映射）的语义。Entity 留在持久化边界内，不作为新增 REST / Feign 公共契约。

BFF 负责页面聚合，Service1 负责核心业务；跨服务只依赖 *-api 契约，不直接引用其他服务的 Service 实现、Mapper 或 Entity。方法与资源授权的接入见 Security。

1. 先定义服务间契约

在 macula-samples-api/macula-samples-service1-api 定义请求表单、查询条件、返回 VO、错误约定和 Feign 接口。现有 ApplicationFeignClient 声明 /api/v1/app 的分页、创建、更新、删除与维护人相关操作，服务发现目标为 macula-samples-service1。

Samples 运行与测试

Mon, 01 Jan 0001 00:00:00 +0000

本页介绍 macula-samples 单仓项目的运行与测试。以下命令均从仓库根目录开始，前端命令另在 Admin 目录执行。

启动前准备

确认 Macula Cloud IAM、Gateway、System 已运行，并登记 BFF 应用与管理端 OAuth Client。复制并编辑仓库根目录的 deploy/.env，然后启动 Samples 本地基础设施：

cp deploy/.env.example deploy/.env
./deploy/scripts/compose.sh config
./deploy/scripts/compose.sh up

该模式启动 MySQL、Redis、Nacos 和初始化任务，应用在 IDE 中以 local profile 运行。Java 服务不会自动加载 .env，需要覆盖的值在 IDE 中设置。

应用启动顺序

Service1、Basic、OpenAPI、Thirdparty。
Admin BFF。
Samples Gateway。
Admin 管理端。

Parent 和 API 契约模块不单独启动。Service1 通过 Flyway 管理数据库迁移。

cd macula-samples-admin
npm ci
npm run dev

浏览器访问 http://127.0.0.1:5800。Vite 的 /api 默认代理到 http://127.0.0.1:6000，登录请求直接访问外部 IAM。

后端测试

在 macula-samples 仓库根目录执行，并显式选择环境：

Samples 打包与本地部署

Mon, 01 Jan 0001 00:00:00 +0000

两种本地运行方式

Samples 的 deploy/ 支持仅启动基础设施的 IDE 模式，以及使用 apps profile 启动完整应用的容器模式。Macula Cloud IAM、Gateway 和 System 是外部依赖，不包含在 Samples 编排中。

检查与启动

在 macula-samples 仓库根目录复制 deploy/.env.example 为 deploy/.env，设置 Cloud IAM、Cloud Gateway、Cloud System Redis 与登记的应用 / OAuth 信息。

./deploy/scripts/compose.sh config-apps
./deploy/scripts/compose.sh up-apps
./deploy/scripts/compose.sh status

完整模式构建并启动各应用，只向宿主机发布 Samples Gateway 6000 与 Admin 5800；BFF、Service1、Basic、OpenAPI、Thirdparty 通过容器网络访问。

普通停止使用 ./deploy/scripts/compose.sh down，保留持久化数据。具体日志、镜像和卷操作以仓库内的 deploy/README.md 为准。

容器与浏览器地址

后端在容器内使用 Compose 服务名；非网关模块的 JWK 地址为 http://macula-samples-gateway:6000/oauth2/jwks。
BFF 的 MACULA_CLOUD_GATEWAY_INTERNAL_URL 是后端访问外部 Cloud 的地址。
管理端 IAM 地址必须能被浏览器访问；Admin 的业务请求通过同源 /api 进入 Samples Gateway。
Admin 的 Docker 运行配置由启动时的 config.js 提供，开发模式由 Vite 环境配置提供。

构建与环境

Samples Parent 定义 local/dev/stg/pet/prd Maven profile。模块构建时选择目标环境，运行时再按部署方式指定对应 Spring profile；配置规范见application.yml 配置规范。