新文章

_config.yml

@@ -1,7 +1,7 @@
 permalink: /:year/:month/:day/:title/
 
 # Site Info
-title: Yanxi.me
+title: Yanxi.me - 阎说
 tagline: "热爱互联网和技术，喜欢探索的终身学习者"
 description: 'A Jekyll theme adapted from <a href="http://lanyon.getpoole.com/" target="_blank">Lanyon</a>. Made by <a href="http://codinfox.github.io" target="_blank">@codinfox</a>.'
 baseurl: ""

_layouts/default.html

@@ -8,8 +8,15 @@
     <div class="qr_code_pc_outer">
       <div class="qr_code_pc_inner">
         <div class="qr_code_pc">
-          <img class="qr_code_pc_img" src="/public/img/qrcode_cfms.jpg" />
-          微信扫一扫<br />关注 财富秘书
+          <img
+            alt="阎说"
+            class="qr_code_pc_img"
+            src="/public/img/qrcode_cfms.jpg"
+          />
+          微信扫一扫<br />关注
+          <span style="font-weight: 600; color: #6a9fb5; font-size: 16px;"
+            >阎说</span
+          >
         </div>
       </div>
     </div>
@@ -24,6 +31,7 @@ <h3 class="masthead-title">
             <img
               class="masthead-logo"
               src="{{ site.baseurl }}/public/img/cfms.png"
+              alt="阎说"
             />
 
             <small style="font-size: 16px; font-weight: 500;">

_posts/2020/2020-01-20-api.md

@@ -0,0 +1,89 @@
+---
+layout: post
+title: 如何更高效的完成 API 联调
+author: 阎曦
+category: 技术
+---
+
+日程开发中，离不开各种联调工作，包括 Web 前后端联调、后端服务之间的联调。API 是应用程序沟通的桥梁，API 联调就是不同程序之间从陌生到熟悉，再到彼此融入的过程。联调工作不是一个人能独立搞定的，需要和其他开发人员，其他团队，甚至其他公司一起来合作完成。
+
+由于联调工作是一个需要彼此合作的才能完成的工作，所以往往会花费大量的时间。服务调用方经常会抱怨服务提供方 API 不够合理，bug 较多，不够稳定；服务提供方会觉得调用方使用方法不正确，因此联调过程会反反复复，花费大量的时间。
+
+如何提高 API 联调效率，让调用双方都能开开心心的完成联调呢，下面分别从 API 提供者和 API 调用者两方面来说一下我的几点经验。
+
+## 对于 API 提供者
+
+根据经验，联调时间长，绝大部分情况都是因为 API 的质量不高导致的反复修改。下面我逐一列出 API 设计者需要注意的几个地方，并给出相应的解决方案。
+
+1. 设计合理的 API，并形成文档
+2. 对错误的处理：提供友好的错误提示，记录错误日志
+3. 对 API 充分的自测
+4. 提供 API 调用示例
+
+<!-- more -->
+
+### 设计合理的 API，并形成文档
+
+API 文档不仅仅是给调用者看的，对于 API 提供者来说也非常重要，相当于是你要实现服务的总目录。因此，我建议在明确业务需求后，具体的开发之前，就要从 API 文档入手开始设计 API。在 API 文档中一般要明确：
+
+- 需要实现哪些 API，各自有什么功能
+- 每个 API 的请求参数有哪些
+- 每个 API 在正常情况下的响应格式
+- 每个 API 在出错时的响应格式，会出现哪些异常
+
+至于如何生成文档，可以通过编辑 wiki 的方式，比如使用 confluence，我个人则更倾向于通过工具来生成文档，工具的好处是定义文档更方便快捷，并且对测试更友好。
+
+比如，如果是基于 Restful 的 API，推荐使用 swagger 来生成文档，swagger 生成的文档可以直接通过网页来完成 API 的测试，还可以方便的生成不同语言的 code。如果后台基于 gRPC 服务，则可以直接用 protobuf 定义作为文档，调用者可以方便的理解，也可以方便的生成客户端代码。如果采用 dubbo 服务，则直接写 java 接口，通过 javadoc 生成文档即可。
+
+### 对错误的处理
+
+错误分为两类：一类是可预期的错误，对这类错误需要分门别类，给出各自的错误码，方便调用者来做处理。另一类是未预料到的错误，一般会在通过某个地方集中捕捉（比如 Fitler, Interceptor, middleware 等)，这类错误可以设置一个特殊的错误码，并给出具体的错误信息。
+
+针对第二类（未预料到的）错误，提供的错误信息越具体越有利于后续的问题查找。有一个情况例外，就是如果接口可以在外网直接访问到，则不要提供具体的出错信息。针对这种情况可以在接口中加一个 debug 字段，只有在测试环境中才显示。比如：
+
+```json
+// 测试环境包含 debug 信息
+{
+    "success": false,
+    "debug": "xxxxx"
+}
+
+// 生成环境无 debug 信息
+{
+    "success": false,
+}
+```
+
+无论针对以上哪种错误，都需要 **记录错误日志**，以备后续的错误定位和分析。
+
+推荐在 API 调用链路中加入 traceId，同一个请求经过的所有链路中都记录 traceId，这对于后续的问题定位帮助很大，debug 信息里可以加入 tranceId，这样服务调用者可以很方便的将出错的 traceId 告诉服务提供者。
+
+### 充分的自测
+
+在给到下游调用者之前，API 开发者必须做充分的自测，测试范围需要覆盖文档中列出的全部 API。如果只做了部分 API 逻辑的修复和更新，则需要测试相关的 API。
+
+- 对于 Restful API
+  - 直接使用 curl 来测试
+  - 使用 Postman
+  - 通过 `.http` 的文件，在 IntelliJ IDEA 和 VS Code(需要安装 REST Client 插件) 中都可以方便的执行
+- 对于 RPC 调用，一般需要通过编写客户端代码来调用
+
+### 提供 API 调用示例
+
+需要给出详细的调用示例，而不仅是笼统的给出哪些参数。比如针对 Restful API，需要指定 Http method，是 get 还是 post, put, ...；必要的 Header 信息，比如 Context-Type 是 `application/x-www-form-urlencoded` 还是 `application/json`, 这些微小的细节有时候会在联调中造成较大困扰，拉长整体联调的时间。
+
+API 调用示例，可以通过以下几种方法来提供调用示例：
+
+- 如果使用 Postman，可以直接导出
+- 提供 curl 调用示例
+- 客户端调用代码示例
+
+## 对于 API 调用者
+
+按照文档并参考示例来调用 API，在联调过程中，如果遇到错误，对比示例 API 调用方法和你的调用方法有哪些异同。如果在示例调用中换成你的参数后，响应是正常的，通过比较示例请求和你的请求的细节差异，就很容易找到问题所在了。
+
+如果按照示例调用的方式仍出现错误，将完整的请求和响应信息给到 API 提供者，方便他们重现错误。有了完整的调用信息，API 提供者也可以比较方便的根据相关的 debug 信息，或者 traceId 信息查询相关的日志来快速定位问题。
+
+## 结束
+
+以上是关于提高 API 联调效率的几条小建议。相信只要做到以上几点，就可以大幅度提高 API 质量和联调效率，小伙伴之间的合作也会更加和谐愉快。

_scss/component/_qrcode.scss

@@ -2,7 +2,7 @@
   position: fixed;
   left: 0;
   right: 0;
-  top: 20px;
+  top: 0;
   color: #717375;
   text-align: center;
 }

dev.sh

@@ -0,0 +1,2 @@
+rm -rf _site
+jekyll s --incremental

home.md

@@ -3,4 +3,4 @@ layout: default
 title: Home
 ---
 
-从 2000 年接触互联网开始，一直从事互联网相关的技术开发工作，同时对对互联网产品、营销、运营都有兴趣。
+欢迎关注微信公众号「阎说」，我们一起来聊互联网、技术、区块链...