run99

分享一下假期完善的 Grape 脚手架

run99 — Tue, 11 Feb 2020 17:52:19 +0800

项目地址：

https://gitee.com/run27017/grape_app_scaffold

Grape App Scaffold

可以说是最完善的 Grape 框架的脚手架

概览

不同于 Rails，使用纯 Ruby 构建的脚手架项目，仅使用 Bundler 和 Rack 运行服务器，非常地轻量。

脚手架包含的组件：

纯 Grape 实现，完全脱离 Rails
支持自动生成 Swagger 文档
单元测试
rake db:setup、rake db:migrate 等
ActiveRecord
pundit：权限验证
overcommit 和 RuboCop：代码质量保证
一个类似于 rails console 的交互式环境
……

已撤回

run99 — Wed, 11 Dec 2019 10:30:49 +0800

Done

Rails API 的整体实践之面向测试的开发

run99 — Sun, 20 Oct 2019 16:22:53 +0800

这个是我的一个系列文章的正文的第二篇了。上一篇是讲接口设计和接口行为的，似乎没有取得太大的反响。这一次，说一说关于 Rails 的东西。

老实讲，Rails 我用了三年有余了，基本上 Web 建站就全靠它。因为实在也没有换用别的框架（这里有个特例，是关于 Grape 的，我会在下一篇讲）或者语言的必要。

我在这里，会讲到有关 Rails 的基本用法的一切，包括如何去构建测试，如何去构建一个完整的 API（就像上一篇文章所讲的那样），以及一些配套的 gem 等。

框架所起的作用，是它提供了一套既有的模式，简化了我们大量的骨架性的工作。我发现，很多初学者，即使不怎么精通这门语言，也能很快上手框架的开发，做一些简单的需求。Rails 就是这样，很多入门选手，可以称之为是一个 Rails 选手，却不是一个合格的 Ruby 选手，只是因为他们是先接触的 Rails，然后再去学 Ruby 的。我不知道这是 Rails 的幸运，还是 Rails 的不幸。

构建一套完整的 API

内容估计有点多，我想放在下次再讲。

面向测试的开发

Rails 指南里关于测试的一节，只讲到了框架为支持测试提供了哪些方法，并没有讲到在实践中如何去构建测试。例如，它对于 Controller 层的一个测试范例这样写道：

# articles_controller_test.rb
class ArticlesControllerTest < ActionDispatch::IntegrationTest
  test "should get index" do
    get articles_url
    assert_response :success
  end
end

什么意思呢？它是说，先是调用一个接口，然后它应该成功。就没了。我不知道这样的测试能说明什么问题。这样的测试，多多少少会让人有点不放心的感觉。

那么，问题来了。Controller 的测试应该怎么去写呢？或者更进一步讲，分层次的测试应该怎么去写呢？的确，测试应该要分层，我们不可能把所有测试都放在 Controller 里面，它会变得臃肿不堪。而事实上，很多测试，如果放在 Controller 内，这样的测试代码会很难写。分层的测试是必要的。

在介绍每个层次的测试怎么写之前，先列出一下测试的层次有哪些：

Controler
Policy
ActiveRecord
ActiveJob
Utils or core

注意到，这里涉及到 MVC 框架里的 M 和 C 的部分，没有 V. 永远不要用代码去测有关视图的部分，它应该用肉眼去验证，或者交给前端开发者报告问题，而不是交给机器。试想一下，下面的测试代码是不是有些愚蠢：

test "should get index" do
  get articles_url
  assert_response :success

  hash = JSON.parse(response.body)
  articles = hash['articles']
  assert_equal 2, articles.length
  article1, article2 = articles
  assert_equal 1, article2.id
  assert_equal 'title 1', article1.title
  assert_equal 'content 1', article1.content
  assert_equal 2, article2.id
  assert_equal 'title 2', article2.title
  assert_equal 'content 2', article2.content
  # ...
end

Controller 的测试

基本模式

Controller 的测试，一般只需要测试正确的接口行为就可以了。我们应该把一般通用的异常情况交给其他的层去测试，如权限问题、参数问题等。所以，一个 Controller 的测试，一般只用写成如下简单的形式：

test "should get index" do
  get articles_url
  assert_response :success
  assert_equals articles(:one, :two, :three), assigns(:articles).to_a
end

这里用到两个组件，fixtures 和 rails-controller-testing. 前者是 Rails 标配的，后者需要你自行在 Gemfile 中添加：

gem 'rails-controller-testing'

这要求，我们需要在 Controller 的处理方法里暴露出@articles实例变量，像这样：

def index
  @articles = Article.index
end

是的，我们去测方法的返回值，而不是 JSON 或者 HTML 视图。将测试粒度控制在我们方便处理的范围，是我们专业测试人员的义务。由于 index 方法不可能返回任何的值，我们就只能测试它的实例变量了。事实上，这些实例变量会交给视图层去渲染，所以也不算对方法造成污染。

当然，这只是一个简单的情况。对于复杂的接口行为，依然可以采用这种方式。你可以暴露出更多的实例变量，一个、两个或更多个，只要是视图层需要的都会暴露出来。然后我们去测试这些实例变量，就好了。

TODO： factory_bot

接口调用

在上面的例子里，接口调用采用的是如下的方式：

get articles_url

有时候需要传递参数，还有 Headers. 这个时候，我推荐在大多数情况下借助一下 factory_bot 的用法：

test "should put update" do
  put article_url(@article), params: { article: attributes_for(:article, title: 'updated title') }
  assert_response :success
  assert_equals 'updated title', assigns(:article).title
end

注意这一节代码attributes_for(:article, title: 'updated title')，它是 factory_bot 的一个方法。该方法会返回:article工厂的属性值，当然title属性会被覆盖为updated title。在测试 update 的接口的时候，我们是不需要测试所有的字段更新的，只用测试自己最关心的几个就好了。当然，不放心的人可以测试完整的。使用attributes_for包装的一个考虑是，它会自动控制 validation 的问题。有可能你只传递title属性接口会报错，用attributes_for包装，就不用关心 validation 的问题了。

Policy 的测试

刚才说过，Controller 层只需要测试正确的行为，一般的错误行为交给其他层去测试。Controller 层最容易出现的错误是：

required 参数没有传
ActiveRecord 的验证没有通过
调用者身份没有权限

错误 1 由捕获异常通用地处理了，可以不必测；错误 2 交给 ActiveRecord 层测试；而错误 3 就是这里讲的 Policy 的测试了。

Policy 的测试是很直白的，就是直接构建 Policy 的类实例，测试它的方法即可：

article = articles(:one)
assert Pundit.policy(article.user, article).update?
assert_not Pundit.policy(users(:two), article).update?

这里测试 update 接口的用户权限问题。我把它们都写在一起了。事实上它告诉我们，唯有article.user才可以更新这篇文章，而其他人则不可以。

Model 的测试

在 Rails 中，Model 层采用的是 ActiveRecord 模式。这里不讨论 ActiveRecord 模式的优劣，但 ActiveRecord 确实是一种包含太多的东西设计模式。在 ActiveRecord 中，会定义到：

数据验证
回调
业务逻辑

这三种情形的测试没有统一的方式一言以蔽之。不过，数据验证倒是可以讲讲。

在应用数据验证测试之前，我推荐使用 fixture 和 factory. Rails 自带有 fixture，而 factory 可以使用 factory_bot 这个 gem.

应用 factory_bot 的时候，注意一点，常规的工厂一定是有效的实例。亦即，往往在 Model 的测试里，下面的测试是第一个要通过的：

test 'normal build should be valid' do
  assert build(:user).valid?
end

如果以上的测试不通过，修改工厂的实现让其通过。只有在这个的基础上，才能去测试其他的验证方法，如：

test 'username should be present' do
  assert_not build(:user, username: nil).valid?
end

test 'username should be unique' do
  user = create(:article)
  assert_not build(:user, username: user.username).valid?
end

我在实践中，像 "username should be valid" 这样的简单测试，我往往不会去写，而是当成一个天然的自信势必会通过的。这涉及到一个测试覆盖率的问题，究竟覆盖多少测试要根据实际情况和个人风格而定。

其他测试

测试说到这里，也算是作结了。其他测试可能包括异步任务的测试、应用框架的测试、核心类或者工具类的测试等等。这些测试方法，作为测试驱动开发的基本涵养，并不是我能够一两句话说清的。为其发声的大师实在是太多太多了，比如在京东图书里搜索 测试驱动开发 会找大一大箩筐的图书条目。

聊聊 Web 接口设计和接口行为

run99 — Mon, 07 Oct 2019 17:47:40 +0800

关于 Web 接口的设计，现在网络上聊得最多得是 RESTful. 但很多人仅仅认为 RESTful 是个接口得设计规范，而忽略了它本质上是一个软件设计架构。

在写这篇文章之前，我在网络上查阅了一些文档资料，并从中筛选出我认为写得不错的博客文档。它们是：

阮一峰的两篇博文：

理解 RESTful 架构

RESTful API 设计指南

和

来自于就浩这口的四篇博文：

聊聊 RESTful - 科普篇

聊聊 RESTful - 接口设计篇（一）

聊聊 RESTful - 接口设计篇（二）

聊聊 RESTful - 接口设计篇（三）

既然已经有这么多的轮子在那里了，我不需要再重复去扯关于 Restful 的各种细节了。所以，我就当下的各种资料，做一些总结性的梳理。是的，也许你不用去读我推荐给你的文章，而直接进入我的总结性的梳理。但你一定得有相关的基础储备，有的是 HTTP 的，有的是 RESTful 的。你的基础储备得有，哪怕是错误的，也是可以的。

理解 RESTful

你应该面向的是 HTTP 而不是 RESTful

当我们将 RESTful 挂在嘴边的时候，可能已经陷入了一个误区。我们忽略了一个事实：HTTP 本身就是 RESTful 的。例如，在 HTTP 里，URI（统一资源定位符）就是用来定位各种资源的。而资源本身可以展示成不同的格式，如 HTML 的、XML 的、JSON 的等等，使用Content-Type这个响应头来标明响应体的格式。另外，GET、POST、PUT、DELETE 就是来表示对资源的操作的。HTTP 本质上就是 RESTful 的，这是因为，当初在设计 HTTP 的时候，潜意识中就是用的 RESTful 的指导思想。某种程度上说，RESTful 是从 HTTP 的规范中归纳出来的。而不是说，它是后来想出的接口设计规范，用于指导如何设计 HTTP 接口。

所以说，当你使用 HTTP 定义你的接口的时候，它天生就应该是 RESTful. 你不应该去强调你的接口如何 RESTful，而应该说明，你的接口哪些部分没有采纳 RESTful.

至于为什么我们现在看到的接口很多都不是那么的 RESTful 的。一个可能的原因是，HTTP 的设计是个逐步演化的过程。它最初可能就只有 GET、POST 这两个方法，至于其他的方法可能是后来再加上去的。还有一点，人都是懒惰的，一个开发者可能并不想去理解那么多的 HTTP 的概念，而造成了某种误用。

用最简单的话来理解 RESTful

REST，即是 Representational State Transfer 的缩写。它的翻译是”表现层状态转化“。我们就不去理解这个词组的意思了，仅仅需要知道的是，在 REST 世界里，你面向的是资源。

资源，可以理解为一切的实体。这个实体，可以是具体的，例如一本书、一张图片，一首歌曲，一个人。也可以是抽象的，例如一种服务、一个行为。我们需要将转账、关注这些行为都要理解成一种资源。

当我们能够定义和定位资源的时候，针对资源的操作大体只有四种，即 GET、POST、PUT、DELETE，即查看、创建、更新、删除这四种操作。这有点像数据库，面对表的数据只能有增删查改这四种一样。一个局限就是，除了这四种，你不能针对资源有其他的操作，其他的操作必须抽象成另一个资源。这就是面向资源的设计。

资源的操作带来的结果是资源状态的改变。HTTP 是无状态的应用层传输协议，资源的状态只保存在服务器，要想对它做任何改变，只能通过操作改变它。

最后再插入一点。我们用 URI（统一资源定位符）来定位资源，用方法（GET、POST、PUT、DELETE）来表示对资源的操作。另外，我们还会使用大量的头部表示各种元信息。元信息是相当重要的，却是最容易被忽视的部分。在响应体中，还会有一个状态码，顾名思义，它表示这次请求的状态转移的结果。

我所觉得的 HTTP 的最佳实践

我不要你觉得，我要我觉得。

在这一篇里，我直接抛出在设计 HTTP 接口时的最佳实践。当然每个人所理解的最佳是不同的，我个人接受反驳，但未必回应。

URI

使用名词定义资源。另外，名词倾向于使用复数。例如用/books表示一个集合，用/books/:id表示单个的资源。唯一的使用单数的情况是，它特指某个单个资源。如/system表示单例资源，/user特指当前用户。

格式

最简单的是一律只使用 JSON. 当然你也可以同时支持其他的格式，如 XML、formData 等，但务必要清晰。

如果只支持 JSON，那么请求体的Accept必须注明application/json，而响应体的Content-Type也必须是application/json.

状态码

务必使用状态码表示状态，如 4xx 是客户端的错误，5xx 是服务端的错误。但 HTTP 的状态码只是一般性的错误表示，不应该作为开发者处理的字段。我一般会在错误的响应体中定义如下格式：

{
    "code": "...",
    "message": "...",
    "details": {}
}

数据格式

数据格式都要用一个字段包装起来，无论是请求体还是响应体。这样做是为了保持一致性和方便以后的扩展。

例如单个 book 资源：

{
    "book": {
        // ...
    }
}

和 books 资源集合：

{
    "books": [
        { // book 1 },
        { // book 2 }
    ],
    "total": "总数"
}

以上是严格按照 RESTful 所说的而产生的最佳实践的标准。但在我的实际开发中，我往往会做一些妥协。（就像写这篇文章一样，我会随性很多，并做出了很多的妥协）

版本号

使用一个特殊的 Header 表示。

鉴权

我习惯使用一个自定义的X-Token的头部，使用 jwt 加密。据说 OAuth 2.0 很流行，但我对这一块并不懂。

可以接受的调整

首先，有些超出”增删查改“范畴的操作并没有抽象成资源，而是作为一个动作附加在资源后面。更确切地说，这一部分没有使用名词，而是作为动词体现在 URI 中。比如，对于关注，我可能是这样设计：

POST /books/:id/star

这里的 star 应理解为动词而不是名词。如果是名词，正如我前面所说的，它应该用复数。

这是我作为 RESTful 的践行者做得不够彻底的地方。

关于 PUT 和 PATCH 的语义，我想在聊聊 RESTful - 接口设计篇（一）里已经解释得很清楚了。在实际的实践中，我往往是把 PUT 作为局部更新来处理的，而 PATCH 和 PUT 一样，并且也不是按照文章说的那样去处理。

关于版本号，我接受在 URI 中加入。这样会更简单。其实，我在实际开发过程中从没有声明过版本号，接口一但有调整都是直接调整，从没有维护过两个版本的情况。这与我只开发公司内部产品，而不是开放 API 有莫大的关系吧。

面向失败的设计

我们听过面向对象的设计，刚刚也接触过面向资源的接口设计。这里我想提的一点，是面向失败的设计。我们现在所接触的系统，其规模大大超过了以往。我们在上手大部分项目的时候，从一开始，就要考虑到它的完备性，以应对方方面面可能出现的失败。那么，从接口设计开始，我们就要考虑全面一些吧。

我们设想一下客户端调用接口的完整过程，它往往是：

客户端发送请求
服务端接收到请求的数据
服务端对请求的数据做验证，希望它符合一定的格式，并且不会对系统的约束造成破坏
如果包含鉴权系统，服务端需要验证鉴权信息，并且需要验证客户端的身份信息是否有对该资源有操作的权限
如果 3、4 的检查都通过，服务端处理数据和请求
服务端将处理的结果返还给客户端

从以上两点看到，服务器需要考虑到一个请求的主要在两个方面：

请求的数据是否符合预期
用户的身份是否对该资源有操作的权限

这分别对应了，在面向失败的设计里，对系统行为预期的最低要求：

接口的调用不会破坏系统的约束
最起码的不该被非法用户入侵

一切更优化的最低要求和行为，都是建立在这两点的基础上的。

检验请求数据

第一件事情就是要检验请求的数据。首先通用的检验我们就不展开说了，如你的数据是合法的 JSON 格式，这应该是在一开始就限制好的。

针对一个合法的 JSON 数据本身，通常需要考虑的问题是：

一个字段是可选的，还是必须的。如果是必须的，在缺乏该字段的时候，系统应该报错。如果是可选的，就需要考虑好它的默认值问题了。
该字段的类型。如标量格式的类型：int、string、boolean 等；又如矢量格式的类型，如：array、object 等。
预期的格式。如一个 string 的格式，它可能需要是一个合法的 email，也可能需要是一个合法的时间字符串，又或者它的长度需要限制在某个范围内。又如一个 int 的值，它的值需要限制在某个范围内。
一定的约束。这种约束可能需要查询数据库才能知晓，但不能破坏。最常见的是唯一性约束。

验证操作权限

第二件事情就是验证操作权限，以防止没有权限的用户对它管辖外的资源造成的破坏。鉴权系统首先需要验证客户端是否提供了有效的身份信息，可选的方案如 jwt. 然后，它需要在两个维度下验证权限：

操作的维度。这个维度是指，用户是否有对该资源有该操作的权限。
字段的维度。这个维度是指，用户对哪些字段拥有操作的权限。

暴露给客户端的数据

在安全的接口设计里，我们需要考虑哪些数据是允许暴露给客户端的。这也包括两个维度：

资源的维度。例如一个管理员只能查看某一个城市下的人口数据，则接口返回中需要筛选出只包含该城市的数据。
字段的维度。一个例子是，在没有付费的普通用户下，需要限制查看某些字段的内容。

这一节提到了三点常见的失败可能。失败的可能错综复杂，将这三点单独拎出来说的原因是，它们是最常见的。所以，在框架选型和项目构建中，一开始就要将这三点囊括进来。现代的 WEB 框架往往能够采用一套通用的方式处理，包括用户代码和测试代码，算是为我接下来讲框架的内容埋下铺垫。

聊聊后端 API 开发的那些事儿

run99 — Tue, 01 Oct 2019 11:45:56 +0800

这是我第一次在 Ruby China 社区发帖。

本来是想写一本书来定义一套标准的开发模式来的。后来想到自己的这些开发经验在真正的牛人面前根本不值得一提，就及时将这个想法扼杀在摇篮里了。但我依然想记下些什么东西，可能更多的是个人笔记的味道，是我自己对这些年开发体验的总结。同时，也希望我写的东西得到更多的交流，让我更能体系化地理解一些东西。

我这次要写的，是关于后端 API 开发的。注意，这不是在探讨全栈的开发，而仅仅是后端 API 的设计与实现。这是因为，后端 API 是我平常工作的主要内容。我们公司的技术选型在一开始就选择了前后端分离，而我个人也在很早期的时候就接触到了 REST 的概念。

我这次写的，是一个系列文章，我觉得一篇文章可能无法涵盖到我要讲的东西。首先，我要总结一下关于 Restful API 设计的本身。这部分内容是与语言无关的，是站在纯设计的角度去思考和阐述。然后，我要说一下有关框架的事情。由于我一直以来都是用 Ruby 开发的，所以我主要讲的就是 Rails 框架和 Grape 框架了。但是，限于篇幅的原因，有些内容可能无法深入展开了，大部分内容都是浅显的。最后要说什么呢？现在还没想好，可能会去实现一套脚手架吧，包含我开发中最常用的模式。

接下来的更新时间，应该在一周以内更新一篇文章吧。总文章数大致在三到四篇的样子。

暂时就这些吧。希望能顺利。期待！