过度封装是封装错地方，应封装语义稳定、复用性强、变更成本高的逻辑（如支付网关适配），并暴露清晰接口；避免封装不稳定逻辑，确保可测试、可Mock、可追踪；路径需可见，命名要揭示意图，参数应可控可配置。
过度封装不是“封装太多”，而是“封装错地方”——它让后续开发者花 10 分钟搞不清一个订单状态为什么能从 SHIPPED 直接变成 PENDING_PAYMENT，或者在调用 FileUploader.upload() 时发现根本没法改超时时间。
封装前先问：这个逻辑有没有稳定契约？
真正值得封装的，是那些语义稳定、跨模块复用、变更成本高的东西。比如支付网关适配、多租户数据隔离策略、风控规则执行入口。这些封装后必须对外暴露清晰接口，而不是把实现藏进 private 方法里就完事。
- 稳定契约的标志：能独立单元测试、可用 Mock 替换、在链路追踪中能被明确标记（如 Dubbo Filter 中打上
payment-gateway-v2标签） - 不稳定的别硬封：比如把三行状态判断抽成
handleStatusTransition()，但没定义状态机或流转图，下次加个新状态就得翻 5 个类找漏掉的分支 - 接口文档必须同步：Spring 项目里
@Operation缺失的 REST 接口，CI 流水线应直接拦截，不能靠人肉 Review 记住
可读性 = 路径可见，不是行数少
企业级代码常被不同人维护多年，可读性的核心是“5 分钟内定位到实际执行点”。跳转超过 3 层（Controller → Service → DomainService → Mapper）就该警惕——这不是深度问题，是路径断裂问题。
- 避免隐式行为：用
@Transactional没问题，但用@Cacheable(key = "#p0.id")却不声明缓存失效逻辑在哪，等于埋雷 - 关键路径保留直读主干：下单流程主干里显式传入
PaymentStrategy和InventoryCheckPolicy，而不是塞进模板方法的钩子里 - 命名要揭示意图而非掩盖实现：
calculateFinalPriceWithTaxAndPromo()比processPrice()更可读，哪怕多敲几个字母
参数暴露比隐藏更考验设计能力
把 storagePath 和 timeout 设为 private 不代表安全，代表懒。真正的封装是控制变化，不是禁止变化。
- 反例：
FileUploader类里所有配置硬编码，业务方只能 fork 或重写 - 正解：提供
setStoragePath(String)和setTimeout(int)，但内部校验路径合法性、超时范围（如timeout > 0 && timeout ） - 边界检查必须在 setter 或 builder 构造时做，不能等到
upload()执行中才抛IllegalArgumentException
最常被忽略的一点：封装合理性没法靠经验判断，得靠工具卡住。静态检查强制接口文档覆盖率、链路追踪标记封装模块耗时、AST 分析跨文件引用深度——这些不是锦上添花，是防止团队在“看起来整洁”和“实际能维护”之间滑向错误方向的护栏。
