Java接口应作为架构级契约设计，强调业务语义命名、动词+名词方法结构、独立contract模块发布、interface定义数据结构、版本化演进及配套Schema校验机制。
Java 接口定义模块间通信，核心是把接口当作“架构级契约”来设计和管理，而不是仅作语法工具。重点不在能不能调用，而在调用双方是否对输入、输出、行为、演进规则有明确、可校验、可协作的一致理解。
接口命名与职责必须体现业务语义
接口名应直指业务能力，而非技术动作或实现细节。比如用 OrderPaymentService 而非 HttpOrderClient；用 InventoryCheckPolicy 而非 InventoryUtil。前者让消费方一眼明白“这是用来核验库存是否足够的策略”，后者只暴露了技术路径，掩盖了职责边界。
方法命名遵循动词+名词结构，且保持语义稳定：
- ✅ reserveStock(itemId, quantity)
- ✅ releaseReservedStock(reservationId)
- ❌ callInventoryApi()（隐藏意图）
- ❌ updateStockStatus()（status 含义模糊，是锁定？扣减？还是同步状态？）
跨模块接口必须独立发布、显式导出
不能把接口定义在某个服务模块的 src/main/java 内部，更不能靠复制粘贴或口头约定。正确做法是：
- 为接口单独建一个 Maven 模块（如
order-api、payment-contract），只放interface和 DTOclass或record - 所有接口和数据类型必须 public 且 exported（即类路径可达，非包私有）
- 消费方通过
compileOnly或api依赖该 contract 模块，而非实现模块 - 禁止在接口中引用实现模块的私有类型（如
private ConfigHelper），否则契约被污染
数据结构统一用 interface 定义，禁用 type 别名替代
跨模块传递的数据对象（如请求体、响应体、回调参数），必须声明为 public interface OrderRequest，而不是 public class OrderRequest 或 type OrderRequest = { ... }。原因在于：
Java Maven 项目审查工作流的通用输入处理。当 Java Maven 项目以 ZIP压缩包或 GitLab 仓库 URL 形式提供且需要...时使用。
立即学习“Java免费学习笔记（深入）”；
-
interface 支持结构检查：当提供方新增字段，消费方未适配时，编译直接报错，不等到运行时报
NullPointerException -
IDE 可跳转、提示、重构：开发时点进
OrderRequest就看到权威定义，无需翻文档或猜 JSON 字段 -
禁止索引签名：如
[key: string]: any或Map<String, Object>会绕过类型约束，等于放弃契约 - 字段名用驼峰、表业务含义：
buyerEmail优于buyer_email或emailAddress（后者未说明是买家）
版本控制与兼容性规则写进契约本身
接口不是写完就固定不变的。规范要求：
- URL 或 RPC 方法名中嵌入版本号（如
/v2/orders、createOrderV2()），避免无感破坏 - 字段变更遵循“只增不删、旧字段保留默认值、废弃字段加
@Deprecated注释并说明替代方案” - 新增必填字段前，先发一版含可选字段的过渡版，给消费方留升级窗口
- 配套提供 OpenAPI 3.0 或 JSON Schema，供前端、测试、网关自动校验
不复杂但容易忽略：契约落地的关键，从来不是语法有多严谨，而是有没有机制确保“定义即共识、发布即生效、变更即通知”。
