API 工程化分享( 五 ) _API

有了这个认知之后我们会做三个事情
首先你的 biz 目录维护的是领域逻辑，你的领域逻辑可以直接依赖 biz.errors 这个目录，因为你会抛一些业务错误出去
第二，我们的 data 有点像 DDD 的 infrastructure ，就是所谓的基础设施，它依赖并实现了 biz 的 repository 和 acl ， repository 就是我们所谓的仓库， acl 是防腐层
因为我们之前讲过它的整个依赖倒置的玩法，就是让我们的 data 去依赖 biz ，最终让我们的 biz 零依赖，它不依赖任何人，也不依赖基础设施，它把 repository 和 acl 的接口定义放在 biz 自己目录下，然后让 data 依赖并实现它
也就是说最终我这个 data 目录也可以依赖 biz 的 errors ，我可能通过查 MySQL ，结果这个东西查不到，会返回一个 sql no rows ，但肯定不会返回这个错误，那我就可以用依赖 biz 的这个 errors number ，比如说 user_not_found ，我把它包一个 error 抛出去，所以它可以依赖 biz 的 errors
目前 Kratos 还不支持根因保存，根因保存是什么呢？刚刚说了你可能是 mysql 报了一个内部的错误，这个内部错误你实际上在最上层的传输框架，就是 HTTP 和 grpc 的 middleware 里面，你可能会把日志打出来，就要把堆栈信息打出来，那么根因保存就是告诉你最底层发生的错误是什么
不支持 Unwrap 就是不支持递归找根因，如果支持根因以后呢，就可以让 Kratos errors 这个 package 可以把根因传进去，这样子既能搞定我们 go 的 wrap errors ，同时又支持我们的状态码和 reason ，大类错误和小类错误，大类错误就是状态码，小类错误就是我刚刚说的用 enum 定义的具体信息，比方说这个商品被下架，这种就不太好去映射一个具体的错误码，你可能是返回一个500 ，再带上一个 reason ，可能是这样的一个做法
Proto Errors：Client从 Client 消费端只能看到 api.proto 和 error.proto 文件，相应的生成的代码，就是调用测的 api 以及 errors enum 定义

使用 Kratos errors.As() 拿到具体类型，然后通过 Reason 字段进行判定；
使用 Kratos errors.Reason() helper 方法（内部依赖 errors.As）快速判定；

拿到这两个文件之后你可以生成相应代码，然后调用 api

文章插图

举个例子，图中的代码是调用服务端 grpc 的某一个方法，那么我可能返回一个错误，我们可以用 Kratos 提供的一个 Reason 的 short car ，一个快捷的方法，然后把 error 传进去，实际上在内部他会调用标准库的 error.As ，把它强制转换成 Kratos 的 errors 类型，然后拿到里面的 Reason 的字段，然后再跟这个枚举值判定，这样你就可以判定它是不是具体的一个业务错误
第二种写法你可以拿到原始的我们 Kratos 的 Error 模型，就是以下这个模型

文章插图

new 出来之后用标准库的 errors.As 转换出来，转换出来之后再用 switch 获取它里面的 reason 字段，然后可以写一些业务逻辑
这样你的 client 代码跨语言，跨传输，跨协议，无论是 grpc ， http ，同样是用一样的方式去解决
IDL Docs

Proto Docs

Proto Docs基于 openapi 插件 + IDL Protobuf 注释（IDL 即定义， IDL 即代码， IDL 即文档），最终可以在 Makefile 中使用 make api 生成 openapi.yaml ，可以在 gitlab/vscode 插件直接查看

API Metadata 元信息用于微服务治理、调试、测试等；

因为我们可以在 IDL 文件上面写上大量的注释，那么当讲到这个地方，你就明白了 IDL 有什么样的好处？
IDL 文件它既定义，同时又是代码，也就是说你既做了声明，然后使用 protoc 可以去生成代码，并且是跨语言的代码，同时 IDL 本身既文档，也就是说它才真正满足了 one source of truth ，就是唯一的事实标准