这是一个创建于 147 天前的主题，其中的信息可能已经有所发展或是发生改变。
虽然写了挺久项目了，但一直以来都有个疑问，看一些项目提供的 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 文档是怎么总结出这些错误码的？难道根据语言不同，有对应的代码分析工具？
7 条回复 • 2024-07-03 21:04:32 +08:00
 |
1
iX8NEGGn 147 天前
每一层 catch 到异常，能处理的处理，不能处理一般会对异常进行转换后才往上抛，而不是无脑的直接一直往上抛，最后抛给用户一个非常底层的异常。
因为同一个底层异常，对于不同上层来说含义可能是不一样的，最终给到用户的异常，应只是用户关心的异常，API 文档中总结出来的错误码只是用户关心的错误码。 比如登录接口，你应该只告诉用户账户不存在、密码错误等异常，对于什么数据库连接失败、各种工具类抛出的异常用户不关心，你应该将它们全部转换成一个“服务器异常”，而不是告诉用户细节：数据库连接失败异常、XXX 工具类异常。 你的误区在于认为直接给每一个异常一个错误码，然后一条路抛到黑，那 API 文档中就要总结出各种各样的异常。 |
 |
2
watzds 147 天前
自定义异常类，异常和错误码已经绑定了，抛出什么异常就是什么错误码
反正我看字节飞书的接口，挺差的，好多都是未知异常 |
 |
3
BeautifulSoap OP @watzds 那么怎么才能知道一个 API 到底会抛上来哪些错误类？比如项目里定义了 100 个错误类，怎么才能知道一个 api 会抛出这 100 个类里的哪些错误类？
|
|
4
iX8NEGGn 147 天前
我好像看错了，你说 API 文档是提供给开发人员的类文档，我还以为是对接 SDK 之类的网络接口文档。
你想说的是如何给每个方法生成运行时异常说明？这是靠规范来达到的，每一个方法都有义务对它抛出的异常进行文档声明，然后上层调用时要进行捕获、转换或继续往上抛，这一层又有义务对它抛出的异常进行声明。 |
|
5
BeautifulSoap OP @iX8NEGGn 感谢回答，但你说的方法依旧没法解决我上面疑惑的一个问题，这些 api 各自可能抛的错误码是怎么整理出来的。
每层都处理异常做转换往上抛，本质上你的意思应该就是希望在最上面一层的 Controller 层或者下一层的 Service 层里将细碎的错误码的粒度降低（也就是说把所有细碎的错误码全处理成几个大类的错误码比如 500 InternalServerError ） 降低错误码的粒度后的确能减少判断错误码的成本，但判断一个 api 会抛哪些错误码的问题依旧没解决。最终做法依旧是程序员人工一行行看代码，总结这个一个 api 可能抛出的所有错误，然后手动写到 api 文档里对吗？ 今后对 api 做变动的话也要重新总结错误码，手动更新 api 文档 |
|
6
BeautifulSoap OP @iX8NEGGn 啊，懂你的意思了。这本质上并不是一个技术问题。而是 api 开发设计问题？是先设计 api ，并且预测这个 api 会产生哪些错误，然后设计 api 文档喝错误代码。最后根据 api 文档喝设计好的错误代码做错误处理，对么？
|
|
7
iX8NEGGn 147 天前
是的，你设计的 API （函数、或者 HTTP 接口）抛出的异常，应该面向你的用户（调用方）来设计，而不是根据你内部实现由其他函数决定。内部实现的其他函数抛出的异常，你函数内能处理的就处理掉，能转换的就转换成你调用方关心的，最后不能处理的才往上抛。
|
Select Language