DeepSeek using Claude Code 重构Oracle Fusion/SAP最佳业务实践：修正Facade 接口、DTO、API及其它编程规范

前言在最初开始编程之前其实我说了要使用facade模式并且还要求claude code写道了相关的SKILL,但是我并没有仔细检测这个SKILL;因为我认为这是一个非常简单的事情。结果等我把安全模块基本开发完了检查代码合规性的时候发现了问题。❯ 讨论在开始开发业务系统之前 我想解决 facade模式以及将来把业务方法导出为API 并支持agent 操作的问题。据上次聊天的信息当前的安全模块没有采用接口是这样的吗● 分析完成。以下是我对当前架构的总结和讨论要点。---当前状态确认是的安全模块完全没有使用 Java 接口。 整个 openlabx.org.cn.security 包中零个自定义接口。当前架构层次Web 层 (JSF Named Bean)↓ InjectFacade (Stateless) —— 薄层仅做委托↓ InjectService (Stateless / ApplicationScoped) —— 实际业务逻辑↓ PersistenceContextEntityManager / JPA当前存在的问题┌────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────┐│ 问题 │ 说明 │├────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────┤│ 无接口契约 │ Facade 和 Service 都是具体类没有抽象接口调用方直接依赖实现 │├────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────┤│ 耦合泄露 │ RoleFacade 的方法签名暴露了 RoleService.PermissionAssignment、RoleService.RoleDiff 等 Service 内部类 │├────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────┤│ 不一致的职责 │ UserFacade 有些方法委托给 Service有些直接操作 EntityManager如 searchUsers()、assignRoleToUser() │├────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────┤│ 覆盖不完整 │ AuthorizationService、AuthorizationEngine 等没有 Facade 包装Web 层直接注入 │├────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────┤│ 无法导出 API │ 没有接口定义无法基于接口自动生成 REST API 或 OpenAPI 文档 │├────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────┤│ Agent 无法操作 │ Agent 需要明确的服务契约输入/输出/语义当前只能通过方法签名猜测 │└────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────┘---建议的改进方向我建议分三个维度来讨论1. 引入接口层 — 建立清晰的业务契约IUserService (接口)↓ implementsUserService (EJB Stateless)↓UserFacade 不再需要或者 Facade 就是 REST 适配层每个业务模块定义接口接口 业务能力的声明。好处- 调用方依赖抽象而非实现- 方便做单元测试mock 接口- 接口本身就是 API 文档2. API 导出策略有了接口后有两种路线- REST 适配层在接口之上加 JAX-RS 资源类自动映射到 REST 端点- 直接 EJB Remote通过 Remote 接口暴露 EJB由应用服务器处理远程调用考虑到你要支持 Agent 操作REST OpenAPI 更合适Agent 可以消费 OpenAPI spec。3. Agent 支持Agent 需要的是- 声明式 API 描述OpenAPI / 自定义注解描述每个操作的前置条件、副作用、参数约束- 统一的调用入口一个 Agent Gateway 接收自然语言意图路由到具体的业务方法- 操作审计Agent 的每次调用都需要记录到 AuditLog---你怎么看这个方向我特别想确认几点1. 接口的粒度 — 是按模块一个接口如 IUserService还是更细2. API 导出的优先级 — 是先做接口抽象再考虑 REST还是一步到位3. Agent 的形态 — 是内部 Agent同进程调用 EJB还是通过 REST 的外部 Agent✻ Churned for 2m 25s❯ 我考虑的是安全就完全不动了因为安全只有一个user需要用API取做。我考虑的是其它CRM/HR/财务。● 明白安全模块基本定型不动了重点是即将开始的 CRM、HR、财务等业务模块。让我确认一下目前是否有这些模块的任何代码。Searched for 1 pattern, listed 1 directory (ctrlo to expand)● 确认了 — 除了安全模块CRM/HR/财务等业务代码完全是空白。这是建立架构的最佳时机。---新业务模块架构讨论从安全模块可以提炼出好的部分Facade 分层、EJB 封装同时补上缺失的部分接口抽象、API 导出、Agent 契约。我建议的分层模型┌─────────────────────────────────────────────┐│ REST API 层 (JAX-RS) │ JSF Web 层 │ ← 两种前端通道├─────────────────────────────────────────────┤│ Facade (Stateless) │ ← 统一入口事务边界│ 实现业务接口 (IBizService) │├─────────────────────────────────────────────┤│ Service (Stateless) │ ← 核心业务逻辑│ 实现同一业务接口 │├─────────────────────────────────────────────┤│ JPA Entity / Repository │ ← 数据持久化└─────────────────────────────────────────────┘关键差异- Facade 和 Service 都实现同一个接口 — Facade 是 Service 的代理不只是简单委托- Facade 是事务边界 安全拦截点 — 不做业务逻辑但负责 Transactional、参数校验、审计日志- Service 是纯业务逻辑 — 可独立单元测试不依赖容器- REST 层直接调用 Facade不经过 JSF需要你确认的几个设计决策在讨论具体的 CRM/HR/财务之前我想先确认三个方向性问题1. 项目结构 — 单模块 vs 多模块 Maven当前是一个 openbusiness-security WAR。后续是- A) 一个大的 openbusiness 多模块项目openbusiness-common、openbusiness-crm、openbusiness-hr、openbusiness-finance- B) 每个业务域独立 Maven 项目各自独立部署2. 接口粒度 — 接口怎么划分- A) 粗粒度每个聚合根一个接口如 ICustomerService、IOrderService- B) 中粒度按功能域划分如 ICustomerCommandService ICustomerQueryServiceCQRS 风格- C) 按你的业务场景来定3. Agent 支持的程度 — 你期望 Agent 怎么操作业务- A) Agent 调用 REST API外部 Agent通过 OpenAPI spec 发现能力- B) Agent 直接注入 EJB Facade内部 Agent同 JVM 进程- C) 两者都要支持通过统一接口抽象这些选择会影响接口设计、异常模型、以及 DTO 的边界定义。你的想法是什么❯ 讨论1 除非部署文件非常大暂时是一个比较大的部署在一起比如销售、服务和市场营销组成的CRM) ,2 、结构粒度一个业务组件一个接口比如用户角色客户)账户商机线索等 3、Agent调用 REST API对我上面的决定有什么意见 我其实不是很专业至少没有真正干过。● 你的三个决定都很合理说实话不像没真正干过的人做的判断。逐个说---对你三个决定的意见1. CRM 作为一个部署单元 → 完全同意销售、服务、市场营销共享客户数据拆成三个微服务反而会带来分布式事务和数据同步问题。这叫 modular monolith——部署是单体内部是模块化的。很多团队拆微服务拆早了最后又合回来。唯一需要警惕的是WAR 包内按 package 做好模块隔离不要让销售代码直接调服务代码的内部类。2. 一个业务组件一个接口 → 粒度刚好账户(Account)、商机(Opportunity)、线索(Lead) 在 DDD 里叫聚合根每个都是一个自然的业务边界。一个接口一个组件维护和理解成本都低。3. Agent 调 REST API → 正确方向这是最灵活的选择。Agent 可以是 Python/Node.js/任何语言写的外部进程通过 OpenAPI spec 发现能力完全解耦。---我真正想提醒的三件事这三件事安全模块做得不好新模块应该从一开始就做对。问题一不要把 JPA Entity 直接暴露到 API 层当前安全模块的 UserFacade 直接返回 User 实体给 Web 层。做 REST API 时这会有三个坑- 懒加载陷阱Entity 离开事务边界后调用 user.getRoles() 直接抛 LazyInitializationException- 敏感字段泄露passwordHash 绝不能出现在 API 响应里- 数据库变更影响 API 契约加个数据库字段API 就变了Agent 就坏了应该做Facade 返回 DTOEntity ↔ DTO 转换在 Facade 层完成。// 不好的做法当前安全模块public User findById(Long userId) {return em.find(User.class, userId); // 暴露了 Entity}// 应该的做法public UserDto findById(Long userId) {User user em.find(User.class, userId);return UserDto.from(user); // DTO 只包含对外需要的字段}问题二Facade 应该是事务和安全的边界而不是透明代理当前 UserFacade.createUser 只是 return userService.createUser(...) 一行委托。这层太薄了没发挥价值。Facade 的真正职责应该是┌─────────────────────────┬─────────┬────────────────────────────────────┐│ 职责 │ 放哪层 │ 原因 │├─────────────────────────┼─────────┼────────────────────────────────────┤│ Transactional 事务控制 │ Facade │ 一个 API 调用 一个事务 │├─────────────────────────┼─────────┼────────────────────────────────────┤│ 参数校验 │ Facade │ 在边界上就拦截非法请求 │├─────────────────────────┼─────────┼────────────────────────────────────┤│ 权限检查 │ Facade │ CheckPermission(account:create) │├─────────────────────────┼─────────┼────────────────────────────────────┤│ 审计日志 │ Facade │ 谁、何时、调了什么方法 │├─────────────────────────┼─────────┼────────────────────────────────────┤│ 业务逻辑 │ Service │ 纯逻辑可测试 │├─────────────────────────┼─────────┼────────────────────────────────────┤│ 数据访问 │ Service │ 通过 EntityManager │└─────────────────────────┴─────────┴────────────────────────────────────┘问题三Agent 不只是调 API还需要元数据Agent 调用 REST API 时它需要知道- 这个操作是读还是写GET/POST- 参数怎么填字段含义、必填/可选、格式约束- 出错怎么办错误码含义- 调用链是什么创建账户 → 关联联系人 → 创建商机这些信息如果靠人工写文档很快就会和代码脱节。应该从接口定义自动生成。推荐的做法接口 (Contract 注解描述)↓实现类 (EJB)↓REST 资源类 (JAX-RS)↓OpenAPI 文档 (自动生成)↓Agent 消费 OpenAPI spec可以在接口上加自定义注解描述业务语义Agent 通过 OpenAPI 这些注解理解每个操作的含义。---总结三个方向决定都对。接下来需要确定的细节是1. DTO 要不要和 Entity 一一对应还是按 API 场景定制列表 DTO vs 详情 DTO2. 权限注解是放在 Facade 接口上还是实现类上3. 要不要我先画一个 CRM 模块比如客户账户的完整接口-Facade-Service-REST 示例代码你看了再调整❯ 关于DTO和权限注解我都没法给出我认为正确的决定我以前只知道同一个实体可以创建一个或多个DTO,关于 按 API 场景定制列表 DTO vs 详情 DTO 完全不清楚我以前理解的Facade接口就是为了更好解耦的技术没有关注权限的细节关于第三个 如果 要编写示例代码我可以提供一个线索的操作步骤文档根据使用的属性编写示例代码1. Navigate to Sales Leads.2. Click the Create Lead (or icon) button on the top right.3. Fill in the required fields in the creation drawer:o Name (Text): A descriptive title for the lead (e.g., 50x Cloud Licenses - TechCorp).o Lead Status (Dropdown): Select Unqualified or New.o Deal Size (Number Currency): Estimated monetary value (e.g., 50,000 USD).o Contact - First Name / Last Name (Text): The primary contact persons name at the prospect company.o Company (Text/Search): Enter the company name. If it exists in the system as an account, search and link it; otherwise, type the new name to create a prospect.o Email / Phone (Text): Contact details for the prospect.● 好的我先解释这两个概念然后用你给的线索创建流程来写完整示例。---DTO 设计解释列表 DTO vs 详情 DTO其实很直观。看一个例子列表页显示线索表格你需要展多少字段可能就 6 个| 名称 | 状态 | 金额 | 公司 | 联系人 | 创建日期 |详情页打开一个线索的完整信息可能 15-20 个字段还包括关联对象。如果列表和详情用同一个 DTO- 列表页加载了 15 个不需要的字段 → 浪费- 详情页需要关联对象数据列表页不需要 → 要么 N1 查询要么少加载导致详情页缺数据所以按场景定制 DTO┌───────────────────┬──────────────┬──────────────────────────────────────────────────────────────┐│ DTO 类型 │ 用途 │ 包含内容 │├───────────────────┼──────────────┼──────────────────────────────────────────────────────────────┤│ LeadListItem │ 表格/列表 │ id, name, status, dealSize, companyName, createdAt (6个字段) │├───────────────────┼──────────────┼──────────────────────────────────────────────────────────────┤│ LeadDetail │ 详情/编辑 │ 全部字段 嵌套的 Contact 信息 Account 信息 │├───────────────────┼──────────────┼──────────────────────────────────────────────────────────────┤│ CreateLeadRequest │ 创建表单提交 │ 表单需要的可填字段 校验注解 │├───────────────────┼──────────────┼──────────────────────────────────────────────────────────────┤│ UpdateLeadRequest │ 编辑表单提交 │ 可修改的字段子集 │└───────────────────┴──────────────┴──────────────────────────────────────────────────────────────┘这不是过度设计——每个 DTO 只包含对应场景真正需要的数据性能和安全都更好。---权限注解放哪里放在 Facade 接口上。原因很简单接口方法上声明 → 谁实现的都要遵守不会漏接口上声明 → 写单元测试只需要 mock 接口不需要启动容器Facade 做检查 → Service 是纯逻辑测试时完全不用管权限Service 不应该知道权限这个概念——它只管业务规则。一个方法到了 Service说明调用者已经通过了权限检查。---示例代码我来根据你的线索创建流程写一套完整代码。先确认一下实体关系- Lead线索一个潜在商机关联一个 Account公司和一个 Contact联系人- Account客户/账户存在系统中的公司可能是已有客户也可能是新创建的 prospect- Contact联系人人的信息我先写好然后你看了再调整方向。● 先创建目录结构。● Bash(mkdir -p /home/clauder/projects/openbusiness/src/main/java/openlabx/org/cn/crm/{entity,dto,service,facade,rest} mkdir -p /home/clauder/projects/openbusiness/…)⎿ Done● Now 写所有示例文件。先从底层开始 — 实体、枚举、通用类。............................................................................................................全部修改完成。验证一下最终的文档结构。Searched for 1 pattern (ctrlo to expand)● 文档结构完整。快速抽查几处关键修改。Read 1 file (ctrlo to expand)● SKILL.md 更新完成。828 行 → 1094 行改动汇总---修改明细┌───────────────────┬──────────────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐│ 节 │ 操作 │ 内容 │├───────────────────┼──────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤│ §2 Facade 模式 │ 重写 │ 接口 Facade Service 三层职责Facade 事务权限审计DTO映射Service 纯业务逻辑 │├───────────────────┼──────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤│ §2 新增 DTO │ 新增 │ 四种场景 DTOListItem/Detail/CreateRequest/UpdateRequest不可变约束禁止 Entity 外泄 │├───────────────────┼──────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤│ §3 数据持久 │ 追加 │ JPA Entity 禁止暴露到 EJB 层之外 │├───────────────────┼──────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤│ §6.4.1 声明式权限 │ 新增 │ RequirePermission 注解定义 PermissionInterceptor CDI 拦截器 使用约束 │├───────────────────┼──────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤│ §7 包命名 │ 更新 │ 新增 sales/service/marketing/hcm/finance新增 common 包子包改为 entity/dto/service/facade/rest/web加职责速查表 │├───────────────────┼──────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤│ §8 REST API │ 新增 │ JAX-RS Resource 标准与 Facade 的关系Agent 消费 OpenAPI 流程URL 路径规范POST/GET/DELETE 约定 │├───────────────────┼──────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤│ §9 生成代码 │ 原 §8 重编号 │ 内容不变 │└───────────────────┴──────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘没有改动的部分- §4 日志规范JUL- §5 密码哈希- §6.1-6.3/6.5-6.10 安全认证体系- 安全模块现有包结构security.ejb 保留不变现在可以用这个更新后的 SKILL 来规范后续 Sales/Service/Marketing 等模块的开发了。