应用分层
分层与依赖方向
业务服务可以采用经典三层作为基础组织方式：Controller → Service → Mapper → 数据库。Macula 不强制所有业务采用同一种架构；需要领域建模时，可在 Service 内进一步划分应用服务与领域能力，并保持接口和持久化边界清晰。
分层架构图
工程目录
各层职责
| 层次 | 负责什么 | 约束 |
|---|---|---|
| Controller | HTTP 适配、输入校验、调用 Service | 不直接访问 Mapper，不放复杂业务规则 |
| Service / impl | 业务规则、操作编排、事务 | 需要原子性时在公开方法声明事务，明确回滚条件 |
| Mapper | 数据访问与查询条件 | 使用参数绑定，限定分页、租户与数据范围 |
| Converter | 各层模型转换 | 沿用 MapStruct，减少手工字段复制 |
Controller 返回业务对象，由 Web Starter 统一封装 Result；不要重复包装或吞掉应交给统一异常处理的异常。查询与写操作分别验证权限，不能依靠前端隐藏按钮控制访问。
模型对象约定
各层模型的传递关系如下：
| 模型 | 用途 | 边界 |
|---|---|---|
| Query | 查询条件、分页与排序 | 可传递至 Service、Mapper；限制任意排序与无限结果集 |
| Form | 新增、更新等写入请求 | 接入 Bean Validation，不直接作为数据库实体 |
| DTO | 跨层或跨服务传输 | 只暴露调用方需要的字段 |
| VO | 面向调用方的展示结果 | 避免泄漏数据库字段与内部实现 |
| BO | 组合查询或业务处理对象 | 用于业务层与组合查询，不默认成为公共接口 |
| Entity | 数据库表映射 | 留在持久化边界内，不作为新增 REST / Feign 公共契约 |
不要直接将客户端提供的租户、角色或身份字段当作可信上下文。身份来自已验证的认证信息，数据范围在服务端查询中落实。
跨服务边界
模型约定同样适用于平台内部微服务调用和跨平台 OpenAPI 交互：
*-api模块保存稳定的 Feign 接口、必要请求 / 返回模型与回退抽象，不反向依赖业务实现。- BFF 组织面向页面的聚合与响应，业务服务实现核心规则和持久化。
- 跨服务通过 API / Feign 调用，不直接引用另一个服务的 Mapper、Entity、Service 实现或资源文件。
- OpenAPI 负责外部 API 聚合；Thirdparty 隔离第三方协议与内部业务模型。
- 公共框架能力由 Macula Boot 提供；登录、菜单及平台权限由 Macula Cloud 提供，业务应用按契约接入。