1 REST

Representational State Transfer

一种网络软件的架构风格

不是标准，不是协议，不是接口，只是一种风格

提出者Roy层参与过HTTP规格文档的撰写

怎么做
以资源（名词，例如用户）为中心
充分利用HTTP现有功能，如动词、状态码、头部字段

举例

创建item（PUT适用于带id创建实体的情况）

1
2
3
4
5
6
7
8


POST /api/v1/items
Content-Type: application/json
消息体 {“amount": 99,  "kind": "income"}
响应 {"resource": {...}} 或 {"errors": {...}}

POST /api/v1/items
Content-Type: application/x-www-form-urlencoded
消息体 amount=99&kind=income

更新item

1
2
3


PATCH /api/v1/items/1
Content-Type: application/json
消息体 {“amount": 99,  "kind": "expense"}

请求一个或多个item

1
2
3
4
5
6
7
8
9


GET /api/v1/items/1
GET /api/v1/items?page=1&per_page=10
GET /api/v1/users/2/items
GET /api/v1/items?user_id=2
GET /api/v1/items?tags_id[]=1&tags_id[]=2
GET /api/v1/items?tags_id=1,2
GET /api/v1/items?sort_by[]=id+asc&sort_by[]=name+desc
GET /api/v1/items?keyword=hi
GET /api/v1/items/search/hi（有争议）

反例
- POST /api/v1/modify_item?id=1
- 对方观点：全用POST，多省事
- 我方观点：有DELETE，不用非要自己想，多费事
总结RESTful
- 看见路径就知道请求什么东西
- 看见动词就知道是什么操作
- 看见状态码就知道结果是什么

200 - 成功 201 - 创建成功 404 - 未找到 403 - 登陆了但没有权限

401 - 未登录 422 - 无法处理，参数有问题 402 - 需付费

412 - 不满足前置条件 429 - （一段时间内）请求太频繁

400 - 其他所有错误，详细原因可以放在 body 里

2 设计API

发送验证码
- 资源：validation_code
- 动作：create(POST)
- 状态码：200 | 201 | 422（邮箱格式不对）| 429（太频繁）
登入登出
- 资源：session（没有s）
- 动作：create | destroy(DELETE)
- 状态码：200 | 422
当前用户
- 资源：me
- 动作：show(GET)
记账数据
- 资源：items
- 动作：create | update(PATCH) | show(GET /items/:id) | index(GET /items?since=2022-01-01&before=2023-01-01) | destroy(DELETE 软删除，做删除标记即可)
标签
- 资源：tags
- 动作：create | update | show | index | destroy

3 路由与分页

3.1 路由

config/routes.rb

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


Rails.application.routes.draw do
	# :api可以视为阉割版的性能更好的字符串
  namespace :api do
    namespace :v1 do 
    	# /api/v1/xxx
      resources :validation_codes, only: [:create]
      resource :session, only: [:create, :destroy]
      resource :me, only: [:show]
      resources :items
      resources :tags
    end
  end
end

命令行输入bin/rails routes可以查看rails为我们创建的全部路由

3.2 验证码的api初步实现

bin/rails g model ValidationCode email:string kind:integer used_at:datetime code:string生成验证码数据model及数据库同步文件

app/models/validation_code.rb

1
2
3


class ValidationCode < ApplicationRecord
	# 暂时不加验证
end

db/migrate/20220315145238_create_validation_codes.rb

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


class CreateValidationCodes < ActiveRecord::Migration[7.0]
  def change
    create_table :validation_codes do |t|
      t.string :email
      t.integer :kind, default: 1, null: false
      t.string :code, limit: 100
      t.datetime :used_at

      t.timestamps
    end
  end
end

输入bin/rails db:migrate同步数据表
创建controller文件：bin/rails g controller Api::V1::validation_codes create，注意路径

app/controllers/api/v1/validation_codes_controller.rb

1
2
3
4
5


class Api::V1::ValidationCodesController < ApplicationController
  def create
    head 201
  end
end

测试一下：curl -X POST http://127.0.0.1:3000/api/v1/validation_codes -v

3.3 items的api及分页功能实现

创建model：bin/rails g model item user_id:integer amount:integer note:text tags_id:integer happened:datetime

app/models/item.rb

1
2


class Item < ApplicationRecord
end

db/migrate/20220315151010_create_items.rb

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


class CreateItems < ActiveRecord::Migration[7.0]
  def change
    create_table :items do |t|
      t.bigint :user_id
      t.integer :amount
      t.text :note
      t.bigint :tags_id, array: true
      t.datetime :happen_at

      t.timestamps
    end
  end
end

同步数据表：bin/rails db:migrate
创建controller：bin/rails g controller Api::V1::Items

app/controllers/api/v1/items_controller.rb

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


class Api::V1::ItemsController < ApplicationController
  def create
    item = Item.new amount: 1
    if item.save
      render json: {resource: item}
    else
      render json: {errors: item.errors}
    end
  end
end

测试一下：curl -X POST http://127.0.0.1:3000/api/v1/items -v，可以多创建几条，用于调试分页功能

3.4 分页功能实现（kaminari/pagy）

Gemfile添加gem 'kaminari'，命令行输入bundle进行安装

如果下载慢，可以在命令行修改bundle源

bundle config mirror.https://rubygems.org https://gems.ruby-china.com

修改kaminari分页配置
- bin/rails g kaminari:config

config/initializers/kaminari_config.rb

1
2
3


# 把注释解开就可以，已经帮我们写好了
config.default_per_page = 10
config.max_per_page = 100

app/controllers/api/v1/items_controller.rb

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


...
  def index
    items = Item.page params[:page]
    # 也可以Item.page(params[:page]).per(100)自定义pageSize
    render json: { resources: items, pager: {
      page: params[:page],
      per_page: 10,
      count: Item.count
    }}
  end
...

测试一下：curl http://127.0.0.1:3000/api/v1/items?page=1

记账app_2_API初步实现

Contents

1 REST

2 设计API

3 路由与分页

3.1 路由

3.2 验证码的api初步实现

3.3 items的api及分页功能实现

3.4 分页功能实现（kaminari/pagy）