接口隔离是按调用方、功能和演进维度切分访问面，而非简单拆分接口；通过OpenAPI多文件契约、角色化SDK生成及跨语言统一治理实现物理级隔离。
接口隔离不是拆接口，而是切访问面
企业级系统里常见的“大而全”契约（比如一个 UserContract 同时暴露注册、登录、删除、导出、审计日志查询）根本问题不在功能多，而在所有调用方都得依赖同一份契约定义。Spring Cloud 或 Dubbo 的服务契约一旦膨胀，下游模块哪怕只查用户信息，也得引入整套依赖，编译慢、升级风险高、IDE 提示冗余方法满屏。
真正要做的，是按「谁调用」「调什么」「凭什么调」三个维度切面：
-
权限面：后台管理需要
deleteUserById()，但 App 端连这个方法名都不该看见 —— 不是靠文档约定“别调”，而是让它在AppUserService接口中根本不存在 -
协议面：Web 端需要带分页的
listUsers(page, size)，IoT 设备端只要getUserById(id)，两个接口返回字段、错误码、重试策略都不同，硬塞进一个UserAPI会导致 DTO 膨胀或运行时类型转换 -
演进面：订单统计类方法（如
getOrderAmountByMonth()）和订单 CRUD 方法生命周期完全不同，前者可能半年不改，后者每周迭代 —— 混在一起会让版本兼容性判断失效
Spring Boot + OpenAPI 下如何物理隔离契约
很多人以为接口隔离只是代码层面的 interface 拆分，但在企业级交付中，契约必须落到可验证的机器可读格式上。OpenAPI（Swagger）3.x 支持 tags 和 components/schemas 的模块化定义，这才是真正落地的起点。
实操建议：
- 每个业务角色对应一个 OpenAPI
yaml文件，例如admin-user-api.yaml、app-user-api.yaml，用tags明确标注适用方 - 共用模型（如
UserDTO）抽到独立shared-models.yaml，通过$ref引入，避免复制粘贴导致字段不一致 - Spring Boot 启动时用
@Profile("admin")控制不同契约对应的 Controller 是否加载，而不是让所有 Controller 都存在、靠权限注解拦截 —— 前者是契约隔离，后者只是运行时过滤 - 生成客户端 SDK 时，指定
--group-id admin-sdk或--group-id app-sdk，确保下游工程只拉取自己需要的 jar
Dubbo 服务接口怎么避免“一个接口打天下”
Dubbo 的 interface 定义天然容易变成 Fat Interface，尤其当团队把 UserService 当成万能胶水来用。关键不是“能不能加方法”，而是“加了之后谁会感知到变更”。
常见错误现象：UserService 新增一个 syncToCRM() 方法，结果订单服务、客服服务、BI 报表服务全部触发重新编译，哪怕它们完全不调用这个方法。
解决路径：
- 把
UserService拆成UserServiceRead（只含getUserById、listUsers）、UserServiceWrite（含createUser、updateUser）、UserServiceAdmin（含deleteUserById、forceResetPassword） - Consumer 端只声明依赖自己需要的 interface，例如订单服务只
@ReferenceUserServiceRead，这样即使UserServiceAdmin接口下线，也不影响订单服务启动 - 避免用泛型或
Map<String, Object>回传数据 —— 这种“灵活”直接废掉接口契约的可推导性，Dubbo 的泛化调用应该仅用于运维脚本，不能进主业务流
最容易被忽略的陷阱：跨语言契约同步
当 Java 服务用 Dubbo，前端用 TypeScript，App 用 Kotlin，三方支付对接用 Python，接口隔离如果只在 Java 层做，等于没做。TypeScript 的 UserReadClient 如果还引用着包含 deleteUser 的完整 UserApi 类型定义，那 Java 层再怎么拆 interface 都白搭。
真正有效的做法：
- 所有语言客户端 SDK 必须从同一份 OpenAPI 定义生成，禁用手工维护类型定义
- 用
x-tagGroups扩展字段在 OpenAPI 中标记接口用途，例如"x-tagGroups": [{"name": "admin", "tags": ["UserAdmin"]}]，生成器据此过滤输出 - CI 流程中加入检查：每次 PR 提交后，扫描所有生成的客户端 SDK，确认
app-client包里没有出现任何含delete、force、audit字样的方法签名 —— 这才是可验证的隔离
接口隔离的复杂点从来不在“怎么拆”，而在于“怎么让所有参与方都只看到自己该看的那一块”。契约一旦脱离代码进入 API 文档、SDK、网关路由规则、监控埋点，就必须统一治理，否则拆出来的接口只是逻辑隔离，物理上依然耦合。
