很好奇 API 单位的 error code（错误码）到底是怎么整理出来的

虽然写了挺久项目了，但一直以来都有个疑问，看一些项目提供的 API 文档，为每个 API 单独提供了可能返回的错误码列表，每个 API 不太一样

我很疑惑的一点就是，这种 API 的错误码列表是怎么整理出来的，因为这种列表并不像是能自动分析出来或人力可以总结出来的东西。因为每个 API 内部都会一层层调用各种方法、service 、repository 。

随着业务复杂，经过一层层的不断调用，一个 API 可能不知不觉就间接地调用了某个会抛出错误码的方法你自己都不知道

比如有几个 API

用户信息 GET /user/xxxxx
预约信息 GET /reservation/xxxxx
主页信息 GET /honme
店铺信息 GET /shops

用户信息 API 为了获取到用户信息，调用了 UserInfoRepository.GetUserInfo(xxxxx) 获取用户信息。这个方法可能会甩出 UserNotExists, UserIsdBanned 等错误码，然后这个方法内部还调用了其他的各种工具函数，可能会甩出 UserIDNotCorrect, DBConnectionError ，等等一大堆错误码。

然后预约信息 API 里因为也要获取用户信息，也调用了 UserInfoRepository.GetUserInfo(xxxxx)。这样预约信息 API 也会扔出 UserNotExists, UserIsdBanned 等错误码

然后主页信息 API 里因为需要展示用户预约信息，所以调用了获取预约信息的相关代码，从而间接调用了 UserInfoRepository.GetUserInfo(xxxxx) 这个方法。最后前三个 API 都经过简单或复杂的关联，最终都调用了 UserInfoRepository.GetUserInfo(xxxxx)，会甩出同样的错误码。而第四个店铺信息 API 因为和用户无关，所以不会甩出对应错误码

这里就有个问题了，一个错误码经过复杂的调用可能会在任何 API 里被抛出来，似乎没有简单方法来分析一个 API 到底会抛出什么错误码。那么一些为 API 总结出各自错误码的 API 文档是怎么总结出这些错误码的？难道根据语言不同，有对应的代码分析工具？

iX8NEGGn

146 天前

每一层 catch 到异常，能处理的处理，不能处理一般会对异常进行转换后才往上抛，而不是无脑的直接一直往上抛，最后抛给用户一个非常底层的异常。

因为同一个底层异常，对于不同上层来说含义可能是不一样的，最终给到用户的异常，应只是用户关心的异常，API 文档中总结出来的错误码只是用户关心的错误码。

比如登录接口，你应该只告诉用户账户不存在、密码错误等异常，对于什么数据库连接失败、各种工具类抛出的异常用户不关心，你应该将它们全部转换成一个“服务器异常”，而不是告诉用户细节：数据库连接失败异常、XXX 工具类异常。

你的误区在于认为直接给每一个异常一个错误码，然后一条路抛到黑，那 API 文档中就要总结出各种各样的异常。

BeautifulSoap

146 天前

@iX8NEGGn 感谢回答，但你说的方法依旧没法解决我上面疑惑的一个问题，这些 api 各自可能抛的错误码是怎么整理出来的。
每层都处理异常做转换往上抛，本质上你的意思应该就是希望在最上面一层的 Controller 层或者下一层的 Service 层里将细碎的错误码的粒度降低（也就是说把所有细碎的错误码全处理成几个大类的错误码比如 500 InternalServerError ）

降低错误码的粒度后的确能减少判断错误码的成本，但判断一个 api 会抛哪些错误码的问题依旧没解决。最终做法依旧是程序员人工一行行看代码，总结这个一个 api 可能抛出的所有错误，然后手动写到 api 文档里对吗？今后对 api 做变动的话也要重新总结错误码，手动更新 api 文档