Skip to content

Commit 71cebe1

Browse files
phodalphodal
committed
[ch13] thinking in content
1 parent 931cfc1 commit 71cebe1

3 files changed

Lines changed: 21 additions & 16 deletions

File tree

‎chapters/chapter-13.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ API 设计是一个非常大的话题，这里我们只讨论：演进、设计
2424
前后端分享 API 的演进史
2525
---
2626

27-
刚毕业的时候，工作的主要内容是用 Java 写网站后台，业余写写自己喜欢的前端代码。慢慢的，随着各个公司的 Mobile First 战略的实施，项目上的主要语言变成了 JavaScript。项目开始实施了前后端分离，团队也变成了全功能团队，前端、后台、DevOps 变成了每个人需要提高的技能。于是如你所见，当我们完成一个任务卡的时候，我们需要自己完成后台 API，还要编写相应的前端代码。
27+
刚毕业的时候，工作的主要内容是用 Java 写网站后台，业余写写自己喜欢的前端代码。慢慢的，随着各个公司的 Mobile First 战略的实施，项目上的主要语言变成了 JavaScript。项目开始实施了前后端分离，团队也变成了全功能团队，前端、后台、DevOps 变成了每个人需要提高的技能。于是如我们所见，当我们完成一个任务卡的时候，我们需要自己完成后台 API，还要编写相应的前端代码。
2828

2929
尽管当时的手机浏览器性能，已经有相当大的改善，但是仍然会存在明显的卡顿。因此，我们在设计的时候，尽可能地便将逻辑移到了后台，以减少对于前端带来的压力。可性能问题在今天看来，差异已经没有那么明显了。
3030

@@ -71,11 +71,11 @@ API 消费者可以继续使用 JavaScript 去编写 API 适配器。后台则
7171
API 的协作设计
7272
---
7373

74-
API 设计实际上应该是由前端人员来驱动的。后台只提高你想要的数据，而不是反过来的。后台提供数据，你从中选择你需要的内容。
74+
API 设计应该由前端开发者来驱动的。后台只提供前端想要的数据，而不是反过来的。后台提供数据，前端从中选择需要的内容。
7575

76-
我们常报怨后台 API 设计得不合理，主要便是因为后台不知道前端需要什么内容。这就好像你接到了一个需求，而 UX 或者美工给老板见过设计图，但是并没有给你看。你能设计出符合需求的界面吗？答案，不用想也知道。
76+
我们常报怨后台 API 设计得不合理，主要便是因为后台不知道前端需要什么内容。这就好像我们接到了一个需求，而 UX 或者美工给老板见过设计图，但是并没有给我们看。我们能设计出符合需求的界面吗？答案，不用想也知道。
7777

78-
因此，当你把 API 的设计交给后台的时候，也就意味着这个 API 将更符合后台的需求。那么它的设计就趋向于对后台更简单的结果，比如后台返回给你一个 Unix 时间，而你需要的是一个标准时间。又或者是反过来的，你需要的是一个 Unix 时间，而后台返回给你的是当地的时间。
78+
因此，当我们把 API 的设计交给后台的时候，也就意味着这个 API 将更符合后台的需求。那么它的设计就趋向于对后台更简单的结果，比如后台返回给前端一个 Unix 时间，而前端需要的是一个标准时间。又或者是反过来的，前端需要的是一个 Unix 时间，而后台返回给你的是当地的时间。
7979

8080
与此同时，按前端人员的假设，我们也会做类似的、『不正确』的 API 设计。
8181

@@ -92,7 +92,9 @@ Swagger
9292

9393
然而，它并不能解决没有人维护文档的问题。但是持续集成与之中的自动化测试可以。
9494

95-
### 测试保证 API
95+
按传统的『瀑布开发模型』来看，这个契约应该由前端人员来创建。因为当后台没有提供 API 的时候，前端人员需要自己去搭建 Mock Server 的。可是，这个 Mock API 的准确性则是由后台来保证的，因此它需要共同去维护。
96+
97+
### 契约：测试保证 API
9698

9799
与其以文档来规范，不如尝试用代码与测试来维护 API
98100

‎ebook.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1588,7 +1588,7 @@ API 设计是一个非常大的话题，这里我们只讨论：演进、设计
15881588
前后端分享 API 的演进史
15891589
---
15901590

1591-
刚毕业的时候，工作的主要内容是用 Java 写网站后台，业余写写自己喜欢的前端代码。慢慢的，随着各个公司的 Mobile First 战略的实施，项目上的主要语言变成了 JavaScript。项目开始实施了前后端分离，团队也变成了全功能团队，前端、后台、DevOps 变成了每个人需要提高的技能。于是如你所见，当我们完成一个任务卡的时候，我们需要自己完成后台 API，还要编写相应的前端代码。
1591+
刚毕业的时候，工作的主要内容是用 Java 写网站后台，业余写写自己喜欢的前端代码。慢慢的，随着各个公司的 Mobile First 战略的实施，项目上的主要语言变成了 JavaScript。项目开始实施了前后端分离，团队也变成了全功能团队，前端、后台、DevOps 变成了每个人需要提高的技能。于是如我们所见，当我们完成一个任务卡的时候，我们需要自己完成后台 API，还要编写相应的前端代码。
15921592

15931593
尽管当时的手机浏览器性能，已经有相当大的改善，但是仍然会存在明显的卡顿。因此，我们在设计的时候，尽可能地便将逻辑移到了后台，以减少对于前端带来的压力。可性能问题在今天看来，差异已经没有那么明显了。
15941594

@@ -1635,11 +1635,11 @@ API 消费者可以继续使用 JavaScript 去编写 API 适配器。后台则
16351635
API 的协作设计
16361636
---
16371637

1638-
API 设计实际上应该是由前端人员来驱动的。后台只提高你想要的数据，而不是反过来的。后台提供数据，你从中选择你需要的内容。
1638+
API 设计应该由前端开发者来驱动的。后台只提供前端想要的数据，而不是反过来的。后台提供数据，前端从中选择需要的内容。
16391639

1640-
我们常报怨后台 API 设计得不合理，主要便是因为后台不知道前端需要什么内容。这就好像你接到了一个需求，而 UX 或者美工给老板见过设计图，但是并没有给你看。你能设计出符合需求的界面吗？答案，不用想也知道。
1640+
我们常报怨后台 API 设计得不合理，主要便是因为后台不知道前端需要什么内容。这就好像我们接到了一个需求，而 UX 或者美工给老板见过设计图，但是并没有给我们看。我们能设计出符合需求的界面吗？答案，不用想也知道。
16411641

1642-
因此，当你把 API 的设计交给后台的时候，也就意味着这个 API 将更符合后台的需求。那么它的设计就趋向于对后台更简单的结果，比如后台返回给你一个 Unix 时间，而你需要的是一个标准时间。又或者是反过来的，你需要的是一个 Unix 时间，而后台返回给你的是当地的时间。
1642+
因此，当我们把 API 的设计交给后台的时候，也就意味着这个 API 将更符合后台的需求。那么它的设计就趋向于对后台更简单的结果，比如后台返回给前端一个 Unix 时间，而前端需要的是一个标准时间。又或者是反过来的，前端需要的是一个 Unix 时间，而后台返回给你的是当地的时间。
16431643

16441644
与此同时，按前端人员的假设，我们也会做类似的、『不正确』的 API 设计。
16451645

@@ -1656,7 +1656,9 @@ Swagger
16561656

16571657
然而，它并不能解决没有人维护文档的问题。但是持续集成与之中的自动化测试可以。
16581658

1659-
### 测试保证 API
1659+
按传统的『瀑布开发模型』来看，这个契约应该由前端人员来创建。因为当后台没有提供 API 的时候，前端人员需要自己去搭建 Mock Server 的。可是，这个 Mock API 的准确性则是由后台来保证的，因此它需要共同去维护。
1660+
1661+
### 契约：测试保证 API
16601662

16611663
与其以文档来规范，不如尝试用代码与测试来维护 API
16621664

‎index.html‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -236,7 +236,7 @@ <h1>我的职业是前端工程师</h1>
236236
<li><a href="#瀑布式开发的-api-设计">瀑布式开发的 API 设计</a></li>
237237
<li><a href="#api-的协作设计">API 的协作设计</a><ul>
238238
<li><a href="#使用文档规范-api">使用文档规范 API</a></li>
239-
<li><a href="#测试保证-api">测试保证 API</a></li>
239+
<li><a href="#契约测试保证-api">契约：测试保证 API</a></li>
240240
<li><a href="#前端测试与-api-适配器">前端测试与 API 适配器</a></li>
241241
</ul></li>
242242
</ul></li>
@@ -1295,7 +1295,7 @@ <h1 id="如何处理好前后端分离的-api-问题">如何处理好前后端
12951295
<p><strong>API 的维护是一件烦人的事，所以最好能一次设计好 API。</strong>可是这是不可能的，API 在其的生命周期里，应该是要不断地演进的。它与精益创业的思想是相似的，当一个 API 不合适现有场景时，应该对这个 API 进行更新，以满足需求。也因此，API 本身是面向变化的，问题是这种变化是双向的、单向的、联动的？还是静默的？</p>
12961296
<p>API 设计是一个非常大的话题，这里我们只讨论：演进、设计及维护</p>
12971297
<h2 id="前后端分享-api-的演进史">前后端分享 API 的演进史</h2>
1298-
<p>刚毕业的时候，工作的主要内容是用 Java 写网站后台，业余写写自己喜欢的前端代码。慢慢的，随着各个公司的 Mobile First 战略的实施，项目上的主要语言变成了 JavaScript。项目开始实施了前后端分离，团队也变成了全功能团队，前端、后台、DevOps 变成了每个人需要提高的技能。于是如你所见，当我们完成一个任务卡的时候，我们需要自己完成后台 API，还要编写相应的前端代码。</p>
1298+
<p>刚毕业的时候，工作的主要内容是用 Java 写网站后台，业余写写自己喜欢的前端代码。慢慢的，随着各个公司的 Mobile First 战略的实施，项目上的主要语言变成了 JavaScript。项目开始实施了前后端分离，团队也变成了全功能团队，前端、后台、DevOps 变成了每个人需要提高的技能。于是如我们所见，当我们完成一个任务卡的时候，我们需要自己完成后台 API，还要编写相应的前端代码。</p>
12991299
<p>尽管当时的手机浏览器性能，已经有相当大的改善，但是仍然会存在明显的卡顿。因此，我们在设计的时候，尽可能地便将逻辑移到了后台，以减少对于前端带来的压力。可性能问题在今天看来，差异已经没有那么明显了。</p>
13001300
<p>如同我在《<a href="https://github.com/phodal/repractise/blob/gh-pages/chapters/frontend.md">RePractise：前端演进史</a>》中所说，前端领域及 Mobile First 的变化，引起了后台及 API 架构的一系列演进。</p>
13011301
<p>最初的时候，我们只有一个网站，没有 REST API。后台直接提供 Model 数据给前端模板，模板处理完后就展示了相关的数据。</p>
@@ -1328,17 +1328,18 @@ <h2 id="瀑布式开发的-api-设计">瀑布式开发的 API 设计</h2>
13281328
<p>最后，再经历痛苦的集成，便算是能完成了工作。</p>
13291329
<p>可是，API 在这个过程中是不断变化的，因此在这个过程中需要的是协作能力。它也能从侧面地反映中，团队的协作水平。</p>
13301330
<h2 id="api-的协作设计">API 的协作设计</h2>
1331-
<p>API 设计实际上应该是由前端人员来驱动的。后台只提高你想要的数据，而不是反过来的。后台提供数据，你从中选择你需要的内容。</p>
1332-
<p>我们常报怨后台 API 设计得不合理，主要便是因为后台不知道前端需要什么内容。这就好像你接到了一个需求，而 UX 或者美工给老板见过设计图，但是并没有给你看。你能设计出符合需求的界面吗？答案，不用想也知道。</p>
1333-
<p>因此，当你把 API 的设计交给后台的时候，也就意味着这个 API 将更符合后台的需求。那么它的设计就趋向于对后台更简单的结果，比如后台返回给你一个 Unix 时间，而你需要的是一个标准时间。又或者是反过来的，你需要的是一个 Unix 时间，而后台返回给你的是当地的时间。</p>
1331+
<p>API 设计应该由前端开发者来驱动的。后台只提供前端想要的数据，而不是反过来的。后台提供数据，前端从中选择需要的内容。</p>
1332+
<p>我们常报怨后台 API 设计得不合理，主要便是因为后台不知道前端需要什么内容。这就好像我们接到了一个需求，而 UX 或者美工给老板见过设计图，但是并没有给我们看。我们能设计出符合需求的界面吗？答案，不用想也知道。</p>
1333+
<p>因此，当我们把 API 的设计交给后台的时候，也就意味着这个 API 将更符合后台的需求。那么它的设计就趋向于对后台更简单的结果，比如后台返回给前端一个 Unix 时间，而前端需要的是一个标准时间。又或者是反过来的，前端需要的是一个 Unix 时间，而后台返回给你的是当地的时间。</p>
13341334
<p>与此同时，按前端人员的假设，我们也会做类似的、『不正确』的 API 设计。</p>
13351335
<p>因此，API 设计这种活动便像是一个博弈。</p>
13361336
<h3 id="使用文档规范-api">使用文档规范 API</h3>
13371337
<p>Swagger</p>
13381338
<p>基于 YAML语法定义 RESTful API，如：</p>
13391339
<p>它会自动生成一篇排版优美的API文档</p>
13401340
<p>然而，它并不能解决没有人维护文档的问题。但是持续集成与之中的自动化测试可以。</p>
1341-
<h3 id="测试保证-api">测试保证 API</h3>
1341+
<p>按传统的『瀑布开发模型』来看，这个契约应该由前端人员来创建。因为当后台没有提供 API 的时候，前端人员需要自己去搭建 Mock Server 的。可是，这个 Mock API 的准确性则是由后台来保证的，因此它需要共同去维护。</p>
1342+
<h3 id="契约测试保证-api">契约：测试保证 API</h3>
13421343
<p>与其以文档来规范，不如尝试用代码与测试来维护 API</p>
13431344
<p>早在 2011 年，Martin Folwer 就写了一篇相关的文章：<a href="http://martinfowler.com/bliki/IntegrationContractTest.html">集成契约测试</a></p>
13441345
<figure>

0 commit comments

Comments
 (0)