接口设计：参数校验、统一返回与错误码规范

很多接口在开发阶段都能跑通，但一旦交给前端、测试或者别的服务方使用，问题就会很快暴露出来：参数规则不清楚、错误信息不稳定、同类接口返回结构不一致、不同异常时状态码和业务码含义混乱。表面上看，这些都不算“核心业务”，但它们会直接影响接口可用性、联调效率和后续维护成本。

接口设计真正要解决的，不只是“把数据返回出去”，而是让调用方在面对成功、失败、异常和边界情况时，都能得到稳定、可理解、可约定的反馈。

为什么接口设计不能只看功能是否完成

因为接口一旦暴露出去，它就是系统和外界沟通的契约。

如果契约不稳定，调用方就很难建立可靠预期。今天参数缺失返回一个字符串，明天格式错误又返回另一种结构；今天资源不存在是 404，明天又变成 200 加一个失败标记。这种接口即使“功能是对的”，协作体验也会非常差。

所以从工程化角度看，接口设计本质上是在设计边界，而边界越清晰，系统越容易协作。

参数是接口的第一道入口，也是很多问题最应该尽早拦住的地方。

如果没有明确校验，非法输入就可能一路流入业务层甚至数据层，最后制造出更难理解的错误。比如空字符串、非法枚举、格式错误、分页范围不合理，这些问题本来可以在入口处快速失败，但如果放过去，后面就可能变成数据库异常、业务状态异常甚至脏数据。

所以参数校验的意义，不只是保证“输入合法”，更是在最靠近边界的地方尽早收缩问题范围。

第一，格式层面的校验要尽量前置。

例如必填项、长度限制、数值范围、枚举取值、时间格式，这些都属于输入层规则，适合在 handler 或请求绑定阶段尽早完成。

第二，业务语义层面的校验要和业务逻辑配合。

例如“当前状态下不能执行这个操作”“用户无权访问这个资源”，这类就不只是参数格式问题，而更接近业务规则。

把这两类校验分清楚，可以让错误含义更明确，也能让接口边界更稳定。

因为调用方真正害怕的不是失败，而是不确定。

如果一个服务的不同接口返回风格完全不同，调用方就不得不为每个接口单独写一套解析逻辑。长远看，这会显著增加前后端联调成本，也会降低服务整体一致性。

统一返回结构的价值，在于让成功和失败都以可预期形式出现。哪怕内部实现不同，外部感知也应该尽量一致。

一个很常见的思路是统一包含。

这样调用方就能先按统一壳子理解结果，再根据具体业务码进入更细处理。

很多项目里的错误码一开始都很随意：某个接口想到一个就写一个，或者干脆全都返回通用失败。短期看开发很快，长期看却很难维护。

错误码真正的价值，是把失败场景分门别类，让调用方和排障方都能快速理解这类问题大概属于哪一层。

例如。

一旦分类有基本规则，后面无论是前端提示、日志检索还是监控归类都会更顺畅。

这是很多初学者最容易混淆的地方。

HTTP 状态码更适合表达协议层和通用语义，例如请求成功、参数错误、未授权、资源不存在、服务器异常；业务错误码则更适合表达更细粒度的业务语义。

所以更合理的理解是：HTTP 状态码负责表达“这一类请求在协议边界上属于什么结果”，业务错误码负责表达“它在业务层具体出了什么问题”。

如果把这两层混为一谈，就很容易出现语义重复或含义模糊。

最典型的反例，就是所有接口都返回：

{
  "code": 500,
  "msg": "failed"
}

这种返回当然简单，但信息量太低。调用方不知道是参数错了、权限错了、资源不存在，还是系统内部异常。排障时你也很难根据响应快速收缩范围。

更合理的思路是，把参数校验、统一响应和错误分类当成一个整体来设计。

也就是说，先在入口层尽量拦住明显非法输入；再通过统一响应结构向外表达结果；最后用相对稳定的错误码体系补充细粒度语义。这样调用方和服务方看到的，就不再是一堆零散接口，而是一套更可预测的服务契约。

给你的 Go 服务设计一个“查询用户信息”和一个“创建用户”接口，要求你补齐下面这些东西。

做完以后你会很明显地感受到：接口设计的难点从来不只是把功能写出来，而是让边界表达得足够稳定。

接口设计是 Go 后端工程化里很容易被低估的一环。参数校验决定问题能不能尽早被拦住，统一返回决定调用方能不能稳定接入，错误码规范决定失败场景能不能被准确理解。把这三件事做好，接口就不再只是“能用”，而会开始具备真正的工程协作价值。