【山竹记账后端】8.【山竹记账后端】测试驱动开发与 API 文档


大纲链接 §

[toc]


 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
sequenceDiagram
    autonumber
    actor U as 用户
    participant B as 浏览器(App)
    participant S as 服务器(Rails)
    participant D as 数据库(PostgresSql)
    participant M as 用户邮箱

    U->>B: 输入邮箱 / 点击发送验证码
    B->>S: 请求创建验证码
    S->>D: 验证成功 / 请求数据库生成验证码
    D-->>S: return email / ValidationCode
    S-->>M: 发送证码到用户邮箱

    U-->>M: 打开邮箱查看
    M-->>U: 返回(邮箱中收到验证码)
    U->>B: 输入验证码 / 点击登录

    B->>S: 请求登录
    S->>D: 验证 email / ValidationCode
    D-->>S: return
    S-->>B: 通过或失败
    B-->>U: 登录成功或失败
  • 输入验证码相关-时序图

1. 测试驱动开发就是先测试再编码 TDD ⇧

安装 rspec_api_documentation

1
gem 'rspec_api_documentation'
  • 将 gem 'rspec_api_documentation' 复制到 GemFile

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    
    source "https://mirrors.ustc.edu.cn/rubygems/"
    # source "https://mirrors.tuna.tsinghua.edu.cn/rubygems/"
    # source "https://rubygems.org"
    
    # Bundle edge Rails instead: gem "rails", github: "rails/rails", branch: "main"
    gem "rails", "~> 7.2.3", ">= 7.2.3.2"
    # Use postgresql as the database for Active Record
    gem "pg", "~> 1.1"
    # Use the Puma web server [https://github.com/puma/puma]
    gem "puma", ">= 5.0"
    
    gem "tzinfo-data", platforms: %i[ mswin mswin64 mingw x64_mingw jruby ]
    gem "bootsnap", require: false
    
    gem "kaminari"
    gem "rspec_api_documentation"
    
    group :development, :test do
    gem "rspec-rails", "~> 8.0.0"
    gem "debug", platforms: %i[ mri mswin mswin64 mingw x64_mingw ], require: "debug/prelude"
    gem "brakeman", require: false
    gem "rubocop-rails-omakase", require: false
    end
  • 运行 bundle install

  • 可忽略以下警告

    1
    2
    3
    4
    
    Don't run Bundler as root. Bundler can ask for sudo if it is needed, and installing your bundle as root will break this application for all non-root users on this
    machine.
    [DEPRECATED] Your Gemfile contains multiple primary sources. Using `source` more than once without a block is a security risk, and may result in installing unexpected gems. To resolve this warning, use a block to indicate which gems should come from the secondary source.
    ...

第一个api用例文档 ⇧

参考文档示例创建两个目录

``zsh mkdir spec/acceptance

vim spec/acceptance/orders_spec.rb

code spec/acceptance/orders_spec.rb ``

spec/acceptance/orders_spec.rb

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
require 'rails_helper'
require 'rspec_api_documentation/dsl'

resource "Orders" do
  get "/orders" do
    example "Listing orders" do
      do_request
      expect(status).to eq 200
    end
  end
end

运行创建文档命令

1
2
rake docs:generate
open doc/api/index.html
  • 运行文档生成命令加前缀 bin/rake docs:generate

发现有报错

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
An error occurred while loading ./spec/acceptance/orders_spec.rb.
Failure/Error: ActiveRecord::Migration.maintain_test_schema!

ActiveRecord::DatabaseConnectionError:
  There is an issue connecting to your database with your username/password, username: mangosteen.

  Please check your database configuration to ensure the username/password are valid.
...
# ------------------
# --- Caused by: ---
# PG::ConnectionBad:
#   could not translate host name "db-for-mangosteen" to address: Name or service not known
#   /usr/local/rvm/gems/ruby-3.1.2/gems/pg-1.6.3-x86_64-linux/lib/pg/connection.rb:944:in `connect_start'
No examples found.

Finished in 0.00594 seconds (files took 5.8 seconds to load)
0 examples, 0 failures, 1 error occurred outside of examples
  • 是由于未连接数据库造成的
  • 在宿主机运行命令 docker start db-for-mangosteen

如果启动失败,比如升级客户端后,删除了之前创建的 Network,可以运行以下命令重新创建数据库

  • 在容器外部宿主机系统运行一行命令

    1
    
    docker run -d --name db-for-mangosteen -e POSTGRES_USER=mangosteen -e POSTGRES_PASSWORD=123456 -e POSTGRES_DB=mangosteen_dev -e PGDATA=/var/lib/postgresql/data/pgdata -v mangosteen-data:/var/lib/postgresql/data -p 5432:5432 --network=network1 postgres:14
  • 注意其中确认 POSTGRES_DB=mangosteen_dev

  • 如果已存在,可以先删掉旧的,运行 docker rm -f db-for-mangosteen,再运行创建命令

  • 运行命令查看 docker ps

  • 成功运行数据库后,再运行文档生成命令 bin/rake docs:generate

再次失败,报错如下:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
Generating API Docs
  Orders
  GET /orders
    ! Listing orders (FAILED)

Failures:

  1) Orders GET /orders Listing orders
     Failure/Error: do_request

     NoMethodError:
       undefined method `rewind' for nil:NilClass

             input.rewind
                  ^^^^^^^
     # /usr/local/rvm/gems/ruby-3.1.2/gems/rspec_api_documentation-6.1.0/lib/rspec_api_documentation/client_base.rb:48:in `read_request_body'
     # /usr/local/rvm/gems/ruby-3.1.2/gems/rspec_api_documentation-6.1.0/lib/rspec_api_documentation/client_base.rb:55:in `document_example'
     # /usr/local/rvm/gems/ruby-3.1.2/gems/rspec_api_documentation-6.1.0/lib/rspec_api_documentation/client_base.rb:43:in `process'
     # /usr/local/rvm/gems/ruby-3.1.2/gems/rspec_api_documentation-6.1.0/lib/rspec_api_documentation/client_base.rb:12:in `get'
     # ./spec/acceptance/orders_spec.rb:7:in `block (3 levels) in <top (required)>'

Finished in 0.13102 seconds (files took 0.63755 seconds to load)
1 example, 1 failure

Failed examples:

rspec ./spec/acceptance/orders_spec.rb:6 # Orders GET /orders Listing orders
  • 这是由于生成的初始接口代码目前未实现 spec/acceptance/orders_spec.rb 其中的路由不存在

重命名测试文件 spec/acceptance/items_spec.rb

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
require 'rails_helper'
require 'rspec_api_documentation/dsl'

resource "Items" do
  get "/api/v1/items" do
    example "Listing items" do
      do_request
      expect(status).to eq 200
    end
  end
end
  • 再次运行命令 bin/rake docs:generate

遇到依赖版本 rspec_api_documentation、rack、rack-test不匹配bug问题

  • 引入补丁 spec/support/rspec_api_documentation.rb

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    
    # spec/support/rspec_api_documentation.rb
    # 修复 rspec_api_documentation 与 Rack 3 / rack-test 2.2 的兼容问题。
    #
    # 现象:Rack 3 / rack-test 2.2 在 GET 等无请求体的请求中,不会向 env
    # 中写入 `rack.input`,导致 `last_request.env["rack.input"]` 为 nil。
    # rspec_api_documentation 6.1.0 的 ClientBase#read_request_body 会直接对其
    # 调用 `rewind`,抛出:
    #   NoMethodError: undefined method `rewind' for nil:NilClass
    #   input.rewind
    #
    # 处理:当 rack.input 为 nil 时返回空字符串,避免对 nil 调用 rewind;
    # 非 nil 时保持原有 rewind + read 行为。
    module RspecApiDocumentation
    class ClientBase
    def read_request_body
      input = last_request.env["rack.input"]
      return "" if input.nil?
    
      input.rewind
      input.read
    end
    end
    end

引入 spec/acceptance/items_spec.rb

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
require 'rails_helper'
require 'rspec_api_documentation/dsl'
require_relative '../support/rspec_api_documentation'

resource "Items" do
  get "/api/v1/items" do
    example "Listing items" do
      do_request

      expect(status).to eq 200
    end
  end
end
  • 再次运行命令 bin/rake docs:generate 成功通过测试

使用 http-server 临时查看生成的api文档 ⇧

  • 目前自动已生成网页文档:doc/api/index.html、doc/api/items/listing_items.html
  • 运行 pnpx http-server ./doc/api/ 即可访问api文档网站 http://127.0.0.1:8080/index.html

    1
    2
    3
    
    # 或者运行以下命令
    cd ./doc/api
    npx http-server .

添加测试用例 validationCode ⇧

  • 创建 touch ./spec/acceptance/validation_codes_spec.rb

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    
    require 'rails_helper'
    require 'rspec_api_documentation/dsl'
    require_relative '../support/rspec_api_documentation'
    
    resource "验证码api" do
    post "/api/v1/validation_codes" do
    example "请求发送验证码" do
      do_request
    
      expect(status).to eq 422
    end
    end
    end
  • 首次期待状态码为 422,因为没有传 email 字段

  • 运行 bin/rake docs:generate 如果测试通过,就会自动生成文档;如果测试失败,就需要去写代码处理这个问题

  • 目前结果如下:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    
    Generating API Docs
    Items
    GET /api/v1/items
    * Listing items
    验证码api
    POST /api/v1/validation_codes
    ! 请求发送验证码 (FAILED)
    
    Failures:
    
    1) 验证码api POST /api/v1/validation_codes 请求发送验证码
     Failure/Error: expect(status).to eq 422
    
       expected: 422
            got: 200
    
       (compared using ==)
     # ./spec/acceptance/validation_codes_spec.rb:10:in `block (3 levels) in <main>'
    
    Finished in 0.11129 seconds (files took 0.6342 seconds to load)
    2 examples, 1 failure
    
    Failed examples:
    
    rspec ./spec/acceptance/validation_codes_spec.rb:7 # 验证码api POST /api/v1/validation_codes 请求发送验证码

请求发送验证码-测试失败


实现代码 validation_codes_controller.rb ⇧

app/models/validation_code.rb

1
2
3
4
class ValidationCode < ApplicationRecord
  # email必填
  validates :email, presence: true
end

app/controllers/api/v1/validation_codes_controller.rb

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
class Api::V1::ValidationCodesController < ApplicationController
  def create
    code = SecureRandom.random_number.to_s[2..7]
    validation_code = ValidationCode.new email: params[:email],
      kind: "sign_in", code: code
    if validation_code.save
      head 200
    else
      render json: { errors: validation_code.errors }, status: 422
    end
  end
end
  • 此时再次运行测试代码 bin/rake docs:generate,测试通过
  • 代码只要满足测试用例,就可以生成api文档给前端
  • 查看生成文档 pnpx http-server ./doc/api/
  • 之后会实现脚本自动部署文档
  • Body 不显示 json 而是 [binary data] 之后处理

请求发送验证码-测试通过

rails 约定大于配置


2. 测试驱动开发就是先测试再编码 ⇧

  • 测试驱动开发
    • Rspec
    • 生成 Api 文档

有个逻辑问题 ⇧

  • api文档不应该展示错误,只需要显示正确请求的文档
  • 422 Unprocessable Content 是不必要的
  • 目录名称 acceptance 也说明了这一点,只放后端接受前端发的请求
  • 如果不接受,最好放到其他目录测试,比如 spec/requests 中

测试用例中发送email,添加中文说明 ⇧

spec/acceptance/validation_codes_spec.rb

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
require 'rails_helper'
require 'rspec_api_documentation/dsl'
require_relative '../support/rspec_api_documentation'

resource "验证码api" do
  post "/api/v1/validation_codes" do
    parameter :email, type: :string

    let(:email) { '1@qq.com' }

    example "请求发送验证码" do
      do_request

      expect(status).to eq 200
    end
  end
end
  • 可以在用例中添加参数的详细描述
  • 真实发送成功需要修改返回状态码
  • 修改类测试用例代码,需要重新 bin/rake docs:generate
  • 查看文档 pnpx http-server ./doc/api/ http://127.0.0.1:8080
    • Content-Type: application/x-www-form-urlencoded 稍后修改为 json 配置
  • 文档
    • parameter :email, type: :string 对参数email的文字描述,生成一个表格
    • let(:email) { '1@qq.com' } 对email的赋值
    • do_request 自动把参数 email 带上,自动展示 body 内容

添加body 修改 app/controllers/api/v1/validation_codes_controller.rb

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
class Api::V1::ValidationCodesController < ApplicationController
  def create
    code = SecureRandom.random_number.to_s[2..7]
    validation_code = ValidationCode.new email: params[:email], kind: "sign_in", code: code
    if validation_code.save
      render json: { code: code }, status: 200
    else
      render json: { errors: validation_code.errors }, status: 422
    end
  end
end
  • 重新 bin/rake docs:generate
  • 查看文档 pnpx http-server ./doc/api/ http://127.0.0.1:8080
    • 后续修改 Body 显示错误 [binary data] 的问题

参考


3. 解决请求中的JSON问题 ⇧

修改 spec/spec_helper.rb

1
2
3
4
5
6
7
8
# ...
require 'rspec_api_documentation'
RspecApiDocumentation.configure do |config|
  # config.format = :json
  # config.response_body_formatter = Proc.new { |response_content_type, response_body| response_body }
  config.request_body_formatter = :json
end
# ...
  • :json 轻量的字符串

修改 spec/acceptance/validation_codes_spec.rb 添加 header

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
require 'rails_helper'
require 'rspec_api_documentation/dsl'
require_relative '../support/rspec_api_documentation'

resource "验证码api" do
  post "/api/v1/validation_codes" do
    parameter :email, type: :string
    header "Content-Type", "application/json"
    let(:email) { '1@qq.com' }

    example "请求发送验证码" do
      do_request
      expect(status).to eq 200
    end
  end
end
  • 重新 bin/rake docs:generate
  • 查看文档 pnpx http-server ./doc/api/ http://127.0.0.1:8080

参考


4. 解决响应中的JSON问题 ⇧

1
git clone git@github.com:jrg-team/rspec_api_documentation.git vendor/rspec_api_documentation

修改包引用 Gemfile

1
2
3
4
# ...
gem "kaminari"
gem "rspec_api_documentation", path: "./vendor/rspec_api_documentation"
# ...
  • 之后运行命令 bundle 或者 bundle install
  • 重新 bin/rake docs:generate
  • 查看文档 pnpx http-server ./doc/api/ http://127.0.0.1:8080
  • 需要注意的是不要将含有子仓库的 ./vendor/rspec_api_documentation 文件提交上去
    • 进入 cd vendor/rspec_api_documentation 删除 rm -rf .git
    • 然后再提交即可

参考


回顾 ⇧

  • 为了是文档中请求 Header有 Content-Type字段,需要在每一次单独请求的时候添加 header "Content-Type", "application/json"
    • 后续可优化
  • 为了让请求Body展示json,需要在 spec/rails_helper.rb 添加配置 config.request_body_formatter = :json
  • 为了让响应Body展示json,需要在 Gemfile 中引用魔改过的版本 gem "rspec_api_documentation", path: "./vendor/rspec_api_documentation"

6. 优化每次都要写请求 header ⇧

避免代码重复 修改 spec/spec_helper.rb

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# ...
RSpec.configure do |config|
  config.before(:each) do |spec|
    if spec.metadata[:type].qual? :acceptance
      require_relative './support/rspec_api_documentation'
      header "Accept", "application/json"
      header "Content-Type", "application/json"
    end
  end
  # ...
end
  • 重新 bin/rake docs:generate
  • 查看文档 pnpx http-server ./doc/api/ http://127.0.0.1:8080

避免把响应Body中的验证码直接展现给用户 ⇧

spec/acceptance/validation_codes_spec.rb

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
require 'rails_helper'
require 'rspec_api_documentation/dsl'

resource "验证码api" do
  post "/api/v1/validation_codes" do
    parameter :email, type: :string
    let(:email) { '1@qq.com' }

    example "请求发送验证码" do
      do_request
      expect(status).to eq 200
      # jsStr = JSON.parse response_body
      # p jsStr
      # 不直接在文档中展示验证码,只返回状态码即可
      expect(response_body).to eq " "
    end
  end
end

app/controllers/api/v1/validation_codes_controller.rb

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
class Api::V1::ValidationCodesController < ApplicationController
  def create
    code = SecureRandom.random_number.to_s[2..7]
    validation_code = ValidationCode.new email: params[:email], kind: "sign_in", code: code
    if validation_code.save
      # 不直接在文档中展示验证码,只返回状态码即可
      # render json: { code: code }, status: 200
      render status: 200
    else
      render json: { errors: validation_code.errors }, status: 422
    end
  end
end

·未完待续·

参考文章

  • 无

相关文章


  • 作者: Joel
  • 文章链接:
  • 版权声明
  • 非自由转载-非商用-非衍生-保持署名