小项目的接口设计：先把边界说清楚

小项目也会因为接口边界模糊而变得难以维护。接口不只是 URL 和参数，它还约定了谁负责校验、错误如何表达、数据何时算完成，以及未来如何兼容变化。边界说得越清楚，团队越少需要靠猜测协作。

先定义资源与动作

把接口涉及的对象列出来，再明确每个对象的生命周期。例如订单可能经历创建、确认、取消和完成，而不是用一个含义模糊的 status 字段承载所有业务。状态变更应有合法路径，重复提交要有幂等策略，避免网络重试造成重复记录。

输入校验要靠近边界完成，但业务规则不要全部塞进控制器。控制器负责把外部请求转换成内部模型，领域逻辑负责做决定，数据层负责持久化。即使项目只有几千行代码，这种分工也能显著降低修改一个字段时的连锁影响。

错误信息要服务于排查

错误响应至少应包含稳定的错误码、面向用户的简短说明和便于日志检索的请求标识。不要把数据库异常或堆栈直接返回给客户端，也不要只返回“操作失败”让调用方无从判断。文档中列出常见错误和重试建议，往往比增加更多功能更能提升接口的可用性。

接口设计完成后，用成功、参数错误、权限不足、资源不存在和重复请求五类案例做一轮契约测试。测试的价值不是证明代码永远正确，而是把边界变成团队共同拥有的一份可执行约定。