vincenting (丁文森)

REST 风格接口中一对多 (Embedding Foreign Entities) 参数设计的疑问

vincenting — Sat, 20 Feb 2016 19:25:39 +0800

最近正在进行我自己项目使用的 REST 风格的规范/实现指导，很大部分的参考了参考了 PostgREST 的接口风格。但是遇到了 Embedding Foreign Entities 查询参数的设计问题，示例情景如下：

在用户自己买书的情景下，用户和书籍为一对多关系，现在需要在一个接口中获得满足一定条件的用户列表、同时获得每个用户最近刚买的三本书的需求。

在一些实现里面，是通过 Hypermedia（超媒体）作为其解决方案，在查询 GET: https://api.example.com/v1/readers?order=created_at.desc&status=eq.online 这样的接口时，会返回如下内容：

[
  {
    "meta": {
      "href": "https://api.vincenting.com/v1/readers/a0f0e-ds012e-aff00f"
    },
    "id": "a0f0e-ds012e-aff00f",
    "name": "vincent",
    "created_at": "2015-11-01T17:02:23.212Z",
    "books": {
       "meta": {
         "href": "https://api.vincenting.com/v1/readers/a0f0e-ds012e-aff00f/books"
       }
    }
  }
]

这样使用起来问题不大，但是当 HTTP2 未普及的今天，带来的问题就是多次请求带来的时间问题，以及服务器需要多次进行解析、权限控制等等操作的性能损耗。

于是在 PostgREST 后面的版本里面加入了：Embedding Foreign Entities 的内容，支持这样的情况下的内容返回。基本思路是对 select 参数进行拓展，显示的申明我需要返回例如 books 里面的所有字段，于是请求的地址变成了 https://api.example.com/v1/readers?order=created_at.desc&status=eq.online&select=*,books{*}，从而服务器会将整个满足条件的内容返回。

于是，可能是 PostgREST 目前不支持或者目前对 PostgREST 的理解有限，对于这种列表（虽然是内嵌的列表），至少需要满足：

条件查询（设计的不好的话很难区分到底是给哪个资源的返回列表进行约束）；
分页支持（目前分页支持是尽可能的遵循 RFC 7233 - Hypertext Transfer Protocol (HTTP/1.1): Range Requests。但是该规范规定客户端不能发起多个资源的 Range 请求，使得很难在 Range 请求头中规定多个资源的分页需求；
排序需求（目前是在 url 的查询参数中以关键字 order 来设计的，问题同一）。

最终目前的疑惑是：

是否有需要考虑这种情况下的查询参数的设计，或者上文中的观点部分内容自身就是错误的
是否有比较好的相关设计范例指的借鉴

注：目前参考的其他文献：

设计一个足够自动生成 RESTful 接口的 Model

vincenting — Sun, 15 Nov 2015 10:47:31 +0800

最近在整理一些 rest 设计的文档，参考了以下文档：

然后抱着造轮子的态度，前段时间实现了一个类似 postgreset 的简易版原型，最近准备在 Sequel 的 Model 基础上进行拓展，目前得到了如下的一个使用 demo：

models/salesman.rb

class Salesman < Sequel::Model(:crm_resources_salesmen)
  include Restfy::Model

 # sequel 中的定义 model 关系的方法
  one_to_many :logs
  one_to_many :tasks
  one_to_many :houses
  one_to_many :contacts
 # 拓展 created_at 和 updated_at
  use_timestamp :createdTimestamp, :updatedTimestamp

 # JSON 字段支持，方便部分非重要字段拓展而不需要每次都修改数据库
  dynamic_fields :details do
    field :sex, type: 'string', required: true, default: 'unknown',
      enums: %w(male female unknown)

    validate_for_sex do |sex|

    end
  end

  # 每个字段的验证，这里考虑引入 helper 机制
  validate_for_name do |name|
    raise Error.new if !name || name.empty?
  end

end

resources/salesman.rb

resource Salesman do
  # 允许哪些操作，包括 单个查询 :get 单个更新 :update 条件查询 :query 创建 :create 批量更新 :patch
  allow_method :update, :get, :query, :create
 # 每个或者多个操作允许哪些字段操作、不允许哪些， 默认 create 是不允许操作 :id 字段的
  exclude_fields_for [:get, :query], :tenantId
  exclude_fields_for_update :tenantId, :groupId
  include_fields_for_create :id

  # 对应的请求操作的权限验证，数据库中的字段满足的条件
  authenticate_for(:update, :create) do |req|
    where(id: req.current_salesman_id)
  end

  authenticate_for(:query, :get) do |req|
    where(tenantId: req.current_tenant_id)
  end

  # 创建时从请求中默认写入哪些数据
  do_before_create(req) do
    self[:tenantId] = req.current_tenant_id
  end
end

目前还在闷头 coding = =。。。为什么不直接用 postgrest：

~~Route 不支持简单的联表查询，会给客户端造成过多的请求负担；~~
Haskell 开发，遇到问题摊手，而且不太易于拓展新的 uri 参数，或者自定义返回格式。

目前想到的就是这么多点，不知道有没有遗漏目前。

updated: 在 @jasl 的建议/提醒下，将表现层的代码单独提取。

使用 Nginx 优化面向侧面的架构

vincenting — Wed, 11 Nov 2015 13:26:04 +0800

面向侧面的程序设计（aspect-oriented programming，AOP），通过将解决特定领域问题的代码从业务逻辑中独立出来，从而提高代码的可维护性。

从主关注点中分离出横切关注点是面向侧面的程序设计的核心概念。分离关注点使得解决特定领域问题的代码从业务逻辑中独立出来，业务逻辑的代码中不再含有针对特定领域问题代码的调用，业务逻辑同特定领域问题的关系通过侧面来封装、维护，这样原本分散在在整个应用程序中的变动就可以很好的管理起来。 - 维基百科

示例是根据最近正在负责的 APP 后端项目简化版，需求简单说如下：

APP 端会对所有请求进行加密，服务器端要对加密结果进行校验，确保正确以及未篡改；
通过手机号来登录，采用基本的 token 机制验证登录；
有企业、小组以及员工的层级关系，后期必须考虑根据公司来分表/集群；
提供涉及到权限的 REST 风格的接口（某种程度上类似 Postgrest，但是进行了拓展，后面会有专门文章介绍）

Version 1st.

思路：首先整个目前项目的主关注点 (core concern) 是 REST 风格的资源服务器 —— 即通过约定俗成的风格来对应具体的数据/资源操作。在这个功能外，需要完成的其他关注点包括：

所有请求加密校验
登录验证
资源的权限管理以及获取

于是，在 Sinatra 中，可以通过 extensions 的方式将请求加密校验完成，配合 before 来进行统一处理：

require 'sinatra/base'

module Sinatra

  module RequestHeadersVerify

    module Helpers
      def headers_valid?
        # 此处省略真实业务代码
        false
      end
    end

    def self.registered(app)
      app.helpers RequestHeadersVerify::Helpers

      app.before do
        unless headers_valid?
          halt 400, json(ResponseErrror::InvalidHeadersError.new)
        end
      end
    end
  end

  register RequestHeadersVerify
end

最终采用"中间件"的方式，在请求的最前面一层（横切关注点 crosscutting concerns）将非法请求进行拦截。

于是紧接着第二个流程，验证用户是否登录，与获取当前联系人所在的公司、小组、以及其管理的小组信息一样，这里最快速/方便的做法就是通过 helpers 来实现：

require 'sinatra/base'

module Sinatra 
  module UserSessionHelpers
    HTTP_USER_TOKEN_KEY = 'HTTP_AUTH_TOKEN'

    def current_user
      @current_user ||= (
        user = User.first token: env[HTTP_USER_TOKEN_KEY]
        halt 400, json(ResponseErrror::InvalidTokenError.new) unless user
        user
      )
    end
  end

  module OrganizationHelpers
    # 这里省略掉相关 helpers 代码
  end

  helpers UserSessionHelpers
  helpers OrganizationHelpers
end

最终在 REST 相关的构建代码中，就不需要去考虑用户请求加密的内容，也不需要去考虑用户是否登录（因为如果需要使用到用户信息但是用户没有登录，会直接抛出错误返回）。只需要按照约定的设计风格，把请求的内容在校验了内容和权限后，转成对应的数据库操作，最终再按照约定的内容返回。

Version 2nd.

第一版已经尽可能的考虑到 解决特定领域问题的代码从业务逻辑中独立出来。但是现实开发里面经常会涉及到多人开发、跨语言合作、更快速的迭代等等的问题，最终需要把他们拆成独立的低耦合度的 Server。于是随之而来的是如何在服务间进行通讯/共享数据。

这里的方案选择通常会根据实际业务以及难易程度来权衡，例如最快捷的 webServer 的方式内部通信，稍微复杂点的基于 TCP 的 RPC 通信方案（例如 thrift），或者某些特殊的情景，例如是生产者/消费者关系的话，则可能通过 MQ 来进行通信。最终我们采用的是通过 Nginx 的 lua 模块来将 server 以面向侧面的思路耦合。

首先，Nginx 的 Lua 模块可以做什么？如果可以，单纯 nginx 和 lua 就可以完成完整的 web 服务。可以连接 redis、memcache、postgresql 等等，同时可以取得请求的所有内容，可以设置返回的头部、正文。配合 lua 的对数据处理能力，基本功能都可以实现。同时 nginx 的 lua 模块整体都是异步，所以性能也相对较好。当然也可以通过 lua 脚本来控制权限，如果验证通过则继续下面的操作，例如是 proxy_pass 代理，简单的示例如下文：

location = /foo {
    access_by_lua_block {
        -- check the client IP address is in our black list
        if ngx.var.remote_addr == "132.5.72.3" then
            ngx.exit(ngx.HTTP_FORBIDDEN)
        end

        -- check if the URI contains bad words
        if ngx.var.uri and
            string.match(ngx.var.request_body, "evil")
        then
            return ngx.redirect("/terms_of_use.html")
        end

        -- tests passed
    }

    proxy_pass http://blah.blah.com;
 }

不过，我们这里将用到的主要还是 proxy_pass, 和 ngx.location.capture，基本代码如下：

-- 禁止任何以下划线开始的请求地址
if string.sub(ngx.var.uri, 2, 2) == "_" then
  ngx.exit(404)
end

local cjson = require "cjson"

local custom_header_prefix = "V-"
local request_args = ngx.req.get_uri_args(64)
local request_body = ngx.req.read_body()
local request_path = ngx.var.uri
local request_method = ngx["HTTP_"..ngx.req.get_method()]

for header, _ in pairs(ngx.req.get_headers()) do
  if string.upper(string.sub(header, 1, 2)) == crm_header_prefix then
    ngx.req.clear_header(header);
  end
end

function res_with_json(body, status)
  ngx.header["Content-Type"] = "application/json"
  ngx.print(body)
  return ngx.exit(status)
end

function request_to_server(uri)
  -- 发起请求至其他地址并取得结果
  res = ngx.location.capture(uri..request_path, {
    body = request_body,
    args = request_args,
    method = request_method,
  })
  local json_response = cjson.decode(res.body)

  -- 解析返回内容
  if not json_response.next == true then
    res_with_json(res.body, res.status)
  end
  for key, value in json_response.params do
     ngx.req.set_header(custom_header_prefix..string.upper(key), value)
  end
  return false
end

上面的代码主完成了清理用户恶意提交的请求头，以及 request_to_server 的代码，实现了将原请求内容转发给另一个接口并获得请求后的内容。得到请求结果后，验证请求的参数。

同时在 nginx 里面通过 stream 和 proxy_pass 的方式来配置多个内部地址：

upstream authentication-server {
    server 192.168.21.1:6011;
    server 192.168.21.2:6011;
}

server {
    location /_authentication {
      proxy_redirect off;
      proxy_set_header Host      $host;
      proxy_set_header X-Real-IP $remote_addr;

      rewrite  ^/_authentication/(.*)  /$1 break;
      proxy_pass http://authentication-server;
    }
}

于是，将两个结合起来，就可以实现通过 lua 脚本把原请求的所有参数，包括头部、正文、请求地址、请求方法都带过去，请求另一个地址（和 proxy_pass 类似），并且可以得到最终返回的结果处理。

拥有这个能力后，便是本文的重点了：在 Sinatra 的第一版本中，最终都是 ruby 代码不断调用方法，来完成整个请求的流程。那如果我们把整个流程的打通交给 Nginx 的话该如何实现呢？

当一个请求进入后，通过 request_to_server 的能力，把请求依次转发给负责横切关注点的服务，例如用户请求校验以及登录校验服务、用户的组织架构服务，最终再去调用主关注点，即本文中的资源服务器；
每次请求完后，根据前一个流程的返回值决定是否进入下一个流程，例如示例中的 lua 脚本是通过返回的 json 里面的 next 参数来决定是否继续往下走。如果没有这个参数则直接返回当前服务的返回值不再继续请求下去；
如果出现了 next: true 这个关键字，则将返回值中的其他内容以请求头的形式传递给下一个服务，且每个服务都会完全信赖这些请求头（所以请求刚进来的时候需要做一些请求头和请求地址处理）。

如果到这里都没有太大问题，你应该可以理解我的意图了。即 Nginx 通过 Lua 脚本来依次请求横切关注点服务器，如果一路顺畅（每次都有 next: true），最终会把携带有横切关注点服务返回的内容的 headers 带给主关注点服务。

于是，在本需求里面，为了保证可拓展性和低耦合性，最终分为了三个服务：

负责请求加密鉴权，用户登录、密码修改的用户验证服务
负责管理企业结构、获取用户权限的组织架构服务
负责具体的 REST 请求处理的资源服务

当一个用户登录的请求过来，因为密码错误或者加密鉴权失败，会在用户验证服务就直接返回错误。因为返回内容中没有 next: true 字段，所以直接返回结果；
当一个用户发起了一个发送短信验证码的服务，这个只是用户验证服务的职能，没有必要继续向下走，于是返回了一个没有 next: true 字段的返回值，于是 Nginx 直接返回结果；
当用户登录的时候，虽然通过了用户验证服务的校验，但是该服务无法获取更多的用户信息，于是把该请求继续传递到组织架构服务，组织架构服务在请求头中拿到了手机号信息，于是直接返回了该手机号所对应的详细信息；
现在发起了一个资源操作的请求，因为用户验证服务无法识别，所以只返回了手机号给 nginx，nginx 继续请求组织架构服务，因为组织架构服务也不能处理，所以继续返回了详细的个人信息给 nginx，nginx 最终拿到这些信息，都通过头部请求了资源服务，然后因为这里是主关注点，也是流程里面最后一个节点，所以通过 proxy_pass 给了资源服务。

最终，这样做的优势：

利用 Nginx 异步的优势来弥补 ruby 服务先天性 IO 处理的不足；
目前只实现了第一条线，即从用户验证 -> 组织信息 -> 资源服务器的顺序，后面如果有需要，可以随时实现其他顺序，而只需要按照在请求头里面加上相应的参数即可，减低耦合性；
三个模块都有各自的业务和特点，可以针对模块去设计缓存方案，而且可以分模块去设计集群方案；
对于开发者而言，更容易完成单个服务的测试用例，而不需要过多在开发过程中关注联调。

原文：使用 Nginx 优化面向侧面的架构

用 Ruby 快速开发一个静态服务全过程

vincenting — Thu, 05 Nov 2015 10:17:02 +0800

最新更新：添加最终演示的 sinatra 项目源码 https://github.com/vincenting/sinatra-image-server-example

由于各种原因，需要给快速客户端提供一个图片上传、生成缩略图、以及获取的接口。使用到的技术关键字：

Sinatra - 基本的 web server 服务；
Sidekiq - 提供异步任务执行支持；
MiniMagick - 提供图片压缩切割支持；
Nginx - 使用 rewrite 和 try_files 实现缩略图访问支持。

最终实现的目标：

支持客户端多图片上传；
URL 中支持参数 resize，后台通过该参数生成对应的图片缩略图，并且可以通过 http://example.com/static/image.jpg@100x100 的方式来访问；
如果访问是缩略图未生产，则访问原图。

前方高能，代码块成堆！

Sinatra 简单的多图上传示例

post '/' do
  result = []
  begin
    params[:images].each do |f|
      filename = SecureRandom.hex(32) + File.extname(f[:filename])
      filepath = "#{ENV['STATIC_ROOT']}#{filename}"
      FileUtils.cp(f[:tempfile].path, filepath)
      result << "#{ENV['STATIC_URL']}#{filename}"
    end
  rescue Exception => e
    halt 400
  end
  json msg: 'upload success.', urls: result
end

然后使用 minitest 来进行测试，或者写一个简单的页面来测试。

<html>
  <head><title>Multi file upload</title></head>
  <body>
    <form action="/" method="post" enctype="multipart/form-data">
      <input type="file" name="images[]" multiple />
      <input type="submit" />
    </form>
  </body>
</html>

使用 Sidekiq 和 MiniMagick 完成缩略图制作

首先需要实现一个简单的缩略图 Worker

class ImageResizeWorker
  include Sidekiq::Worker

  def perform(image_path, sizes)
    image_info = {}
    [:dirname, :extname].each do |f|
      image_info[f] = File.send f, image_path
    end
    image_info[:basename] = File.basename image_path, image_info[:extname]
    sizes.each do |size|
      output_path = File.join(image_info[:dirname],
                              "#{image_info[:basename]}@#{size}#{image_info[:extname]}")
      resize_image image_path, size, output_path
    end
  end

  private
  def resize_image(image_path, output_size, output_path)
    image = MiniMagick::Image.open image_path
    image.resize output_size
    image.write output_path
  end

end

使用测试用例测试 worker，测试用例基本如下：

require_relative 'spec_helper'

describe ImageResizeWorker do
  before do
    @test_image_path = File.join(File.dirname(__FILE__), 'test_image_files', 'wensen.jpg')
    @worker = ImageResizeWorker.new
  end

  it 'should resize images without any error' do
    @worker.perform(@test_image_path, %w(100x100 200x200))
  end

  it 'should has the same extname' do
    @worker.perform(@test_image_path, %w(100x100 200x200))
    assert File.exist?(File.join(File.dirname(@test_image_path), "wensen@100x100.jpg"))
    assert File.exist?(File.join(File.dirname(@test_image_path), "wensen@200x200.jpg"))
  end

  it 'should assert_equal name and size' do

    @worker.perform(@test_image_path, %w(40x50 100x80 120x120))
    Dir[File.join(File.dirname(__FILE__), 'test_image_files', '*@*.*')].each do |f|
      image = MiniMagick::Image.open(f)
      size = File.basename(f, '.*').split('@').last.split 'x'
      assert_equal image.width, size.first.to_i
      assert_equal image.height, size.last.to_i
    end
  end

  after do
    Dir[File.join(File.dirname(__FILE__), 'test_image_files', '*@*.*')].each { |f| File.delete f }
  end
end

当测试到大小比例和原图不等的时候突然发现报错了，发现 resize 没有自动切割（或许是有参数我不知道）。于是就要继续拓展 resize_image 方法来支持切割。此处略去一大块代码。

修改 webserver 的代码，在图片拷贝到上传文件夹后，

unless ENV['RACK_ENV'] == 'test'
  ImageResizeWorker.perform_async filepath, (params[:resize] || '').split(',')
end

然后就是测试测试，这个时候基本上一个支持多图片上传，并且支持后台图片缩略图的 server 就完成了。

Nginx 优化图片访问方式

在下面的讨论内容之前，先贴一个地址 IF IS EVAL。

需求：访问 /static/url.jpg@100x100 可以访问到图片 /opt/static/url@100x100.jpg 并返回，如果这个时候缩略图还没生成，就先返回原图。

先不管第二个需求，写出来的基本上就是如下的配置：

server {
    root /opt;
    location /static/ {
       rewrite  ^/static/(\w+)\.(\w+)@(\w+)  /static/$1@$3.$2 break;
    }
}

默认完成图片的访问地址与硬盘地址对应，如果满足 rewrite 正则则执行 rewrite，即需求中的第一点。现在需要完成第二条需求，即如果默认的访问失败的话，就去访问原图，于是这里需要使用到 try_files - 按照特定顺序来尝试 file 直到第一个成功。

server {
    root /opt;
    location /static/ {
       try_files $uri $uri.origin;
       rewrite  ^/static/(\w+)\.(\w+)@(\w+)  /static/$1@$3.$2 break;
    }
    location ~ \.origin$ {
    rewrite  ^/static/(\w+)\@(\w+).(\w+).origin$  /static/$1.$3 break;
    }
}

于是最终就变成了如上的配置文件（虽然一路并不顺利）。在同时使用 try_files 和 rewrite 的时候，发现执行顺序是先尝试第一个，即 $uri，然后执行 /static/ 中的 rewrite，此时的 $uri 其实已经变成了 rewrite 后的内容，所以当 /static/ 没有找到文件换为 $uri.origin 这里的 $uri 已经不是原来的请求路径，而是 rewrite 后的。所以对于特别是新人，在写 nginx 配置的时候要记得看 error 输出，如果没有的话记得开启，里面会给出很多有价值的内容。

吐槽完毕，最终在 sinatra 中通过 before 的方法加上基本的鉴权项目就上了测试环境。

[简信] 智能邮件投递测试版

vincenting — Wed, 29 Oct 2014 19:21:20 +0800

当前完成情况

目前已经可以供发送量小中型用户使用，基本的功能已经测试通过。

HTTP 协议的邮件投递，包括队列等待式投递、立即投递，立即投递又可选阻塞式投递（请求直接返回投递结果，默认投递后返回邮件 ID，并通过回调告知投递结果）
针对收件域名的发送频率控制
发送异常的根据关键字的默认处理以及可人工针对发送日志指定处理方法

下面要完成的功能

SMTP 协议的邮件投递
开发文档，包括模块的设计以及通信的规则
使用文档
安装工具，方便快速安装

传送门：

项目主页： https://github.com/jianxinio/postman 测试版本安装文档： https://github.com/jianxinio/postman/blob/master/docs/install.md

技术关键字

ruby[padrino], golang, nodejs, tls, redis, mysql, semantic-ui

非技术的内容

这个项目由于目前由一个人开发，所以整体（性能以及安全、可靠性）很局限于个人认知水平。很希望有更多的人参与，给邮件发送一个更好的选择。如果你了解上面的技术关键字中的一点或者几点，欢迎先了解下大概的代码，提出代码中的缺陷/提交缺陷的改进代码。目前整体的开发文档会在后面快速跟进（由于公司新项目，可能下面速度会稍慢）。还有我蹩脚的英文，后面依旧是希望同时提供中文/英文两个版本的页面/文档，也欢迎加入。