meta-api 0.0.1

data/docs//347/264/242/345/274/225.md

@@ -0,0 +1,173 @@
+# 索引
+
+## 属性校验
+
+### `validate`
+
+通用的校验器，可传递一个自定义的块。注意，如果校验不通过，需要主动地抛出 `Meta::JsonSchema::ValidationError`. 例如：
+
+```ruby
+property :mobile, validate: lambda do |value|
+  raise Meta::JsonSchema::ValidationError, '手机号格式不正确' unless value =~ /\d+/
+end
+```
+
+### `required`
+
+有关必须要传递的字段可通过 `required: true` 设置。
+
+```ruby
+property :name, required: true # 必须
+property :age, required: false # 非必须
+```
+
+对于字符串属性，即使是空白字符串也无法通过 `required` 校验。这时可通过设置 `allow_empty: true` 来改变这一行为。
+
+```ruby
+property :name, required: { allow_empty: true }
+```
+
+数组属性默认是允许空数组的。如果你不喜欢这种行为，需明确设置 `allow_empty` 为 `false`.
+
+### `format`
+
+`format` 校验可传递一个正则表达式选项，参数需匹配正则表达式代表的模式。
+
+```ruby
+property :date, format: /^\d{4}-\d{2}-\d{2}$/
+```
+
+### `allowable`
+
+对于枚举值来说，通过 `allowable` 来定义可选项。
+
+```ruby
+property :gender, allowable: ['male', 'female']
+```
+
+如果用户传递了不同于 `male` 或 `female` 的值，就会报错。
+
+## 错误列表
+
+框架中使用 `rescue_error` 捕获异常，框架能够抛出的异常包括：
+
+- `Meta::Errors::NoMatchingRoute`：路由不匹配时。
+- `Meta::Errors::ParameterInvalid`：参数存在异常时。
+- `Meta::Errors::RenderingInvalid`：响应值存在异常时。
+- `Meta::Errors::UnsupportedContentType`：框架只支持 `application/json` 的参数格式。当客户端的请求体不是这个格式时，会抛出这个错误。
+
+## I18n
+
+框架默认提供的语言是 `zh-CN`，可通过文件 `config/locales/zh-CN.yml` 查看可配置的内容。如果需要添加其他语言的支持，需要自行配置。
+
+## `lock` 系列方法
+
+`locked` 方法返回一个新的实体，它将若干选项锁定。例如，锁定某个实体为 `scope: 'full'`：
+
+```ruby
+# 如下定义一个 Entity
+class ArticleEntity < Meta::Entity
+  property :title, type: 'string'
+  property :content, type: 'string', scope: 'full'
+  property :hidden, type: 'boolean', scope: 'o'
+end
+
+# 在 using 时锁定 scope
+params do
+  property :article, using: ArticleEntity.locked(scope: 'full')
+end
+```
+
+如上，`article` 内容仅包含字段 `title`、`content`.
+
+再例如，我们也可以去掉某些指定的字段，这时用到 `exclude: ...` 选项。下面的例子将达到与上面例子等效的结果：
+
+```ruby
+# 在 using 时去掉某些字段
+params do
+  property :article, using: ArticleEntity.locked(exclude: [:hidden])
+end
+```
+
+注意 `exclude` 的传递格式，它接受一个数组，并且字段应用符号而不是字符串。
+
+最后一个示例是如何处理缺失字段的。在处理请求参数时，我们有时候需要包括缺失字段，有时候需要去掉缺失字段。默认情况下是按照前者处理的，如果需要按照后者的方式处理，需要锁定选项 `discard_missing: true`：
+
+```ruby
+# 在 using 时不包括缺失字段
+params do
+  property :article, using: ArticleEntity.locked(discard_missing: true)
+end
+```
+
+我们也可以综合这几个选项（由于综合 `scope` 和 `exclude` 往往没有意义，这里我们只综合 `scope` 和 `discard_missing`）：
+
+```ruby
+params do
+  property :article, using: ArticleEntity.locked(scope: ['full'], discard_missing: true)
+end
+```
+
+如上，`scope` 选项也可以传递数组的。
+
+除了 `locked` 方法，还包括几个便捷方法。例如 `lock` 方法，它与 `locked` 在某种程度上等价：
+
+```ruby
+ArticleEntity.lock(:scope, 'full')         # 它与 locked(scope: 'full') 等价
+ArticleEntity.lock(:discard_missing, true) # 它与 locked(discard_missing: true) 等价
+```
+
+还有 `lock_xxx` 便捷方法：
+
+```ruby
+ArticleEntity.lock_scope('full')           # 它与 locked(scope: 'full') 等价
+```
+
+## `parameters` 、`request_body` 和 Open API 规格定义
+
+在 Open API 中，参数和请求体是分开定义的，它们不属于同一个语义。下面是一个 HTTP 请求的示例：
+
+```http
+POST /request?foo=foo
+X-Bar: bar
+
+{
+  "user": ...
+}
+```
+
+其中 `foo=foo` 和 `X-Bar: bar` 是参数，而 JSON 格式的 `{ "user": ... }` 才是请求体。
+
+在 Meta 框架中，为了方便，可以用同一个宏命令（即 `params`）来定义参数和请求体：
+
+```ruby
+params do
+  param :foo, in: 'query'
+  param 'X-Bar', in: 'header'
+  param :user, type: 'object'
+end
+```
+
+而事实上，Meta 框架也给出了分开定义参数和请求体的的宏命令。也许有些混淆，`parameters` 宏专用于定义参数，`request_body` 宏用于定义请求体：
+
+```ruby
+parameters do
+  param :foo, in: 'query'
+  param 'X-Bar', in: 'header'
+end
+request_body do
+  property :user, type: 'object'
+end
+```
+
+而在应用中，也许有些混淆，`params`、`parameters`、`request_body` 能够获取到参数和请求体：
+
+```ruby
+action do
+  params       # 合并获取参数和请求体
+  parameters   # 专用于获取参数
+  request_body # 专用于获取请求体
+end
+```
+
+面对这两种使用方式，有何使用上的建议呢？我的建议是，你习惯用哪种就用哪种。

data/examples/lobster.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# 一个示例 Rack 应用，运行方式：`ruby -Ilib <this-file>`
+
+require 'zlib'
+
+# Paste has a Pony, Rack has a Lobster!
+class Lobster
+  LobsterString = Zlib::Inflate.inflate("eJx9kEEOwyAMBO99xd7MAcytUhPlJyj2
+    P6jy9i4k9EQyGAnBarEXeCBqSkntNXsi/ZCvC48zGQoZKikGrFMZvgS5ZHd+aGWVuWwhVF0
+    t1drVmiR42HcWNz5w3QanT+2gIvTVCiE1lm1Y0eU4JGmIIbaKwextKn8rvW+p5PIwFl8ZWJ
+    I8jyiTlhTcYXkekJAzTyYN6E08A+dk8voBkAVTJQ==".delete("\n ").unpack("m*")[0])
+
+  LambdaLobster = lambda { |env|
+    if env[Rack::QUERY_STRING].include?("flip")
+      lobster = LobsterString.split("\n").
+        map { |line| line.ljust(42).reverse }.
+        join("\n")
+      href = "?"
+    else
+      lobster = LobsterString
+      href = "?flip"
+    end
+
+    content = ["<title>Lobstericious!</title>",
+               "<pre>", lobster, "</pre>",
+               "<a href='#{href}'>flip!</a>"]
+    length = content.inject(0) { |a, e| a + e.size }.to_s
+    [200, { Rack::CONTENT_TYPE => "text/html", Rack::CONTENT_LENGTH => length }, content]
+  }
+
+  def call(env)
+    req = Rack::Request.new(env)
+    if req.GET["flip"] == "left"
+      lobster = LobsterString.split("\n").map do |line|
+        line.ljust(42).reverse.
+          gsub('\\', 'TEMP').
+          gsub('/', '\\').
+          gsub('TEMP', '/').
+          gsub('{', '}').
+          gsub('(', ')')
+      end.join("\n")
+      href = "?flip=right"
+    elsif req.GET["flip"] == "crash"
+      raise "Lobster crashed"
+    else
+      lobster = LobsterString
+      href = "?flip=left"
+    end
+
+    res = Rack::Response.new
+    res.write "<title>Lobstericious!</title>"
+    res.write "<pre>"
+    res.write lobster
+    res.write "</pre>"
+    res.write "<p><a href='#{href}'>flip!</a></p>"
+    res.write "<p><a href='?flip=crash'>crash!</a></p>"
+    res.finish
+  end
+end
+
+if $0 == __FILE__
+  # :nocov:
+  require 'rack'
+
+  app = Lobster.new # or Lobster::LambdaLobster
+  Rack::Server.start(
+    app: Rack::ShowExceptions.new(Rack::Lint.new(app)), Port: 9292
+  )
+  # :nocov:
+end

data/examples/rack_app/README.md

@@ -0,0 +1,3 @@
+# Demo Rack Application
+
+一个示例 Rack 应用，可以看到中间件的用法以及它们如何交互。

data/examples/rack_app/config.ru

@@ -0,0 +1,6 @@
+require 'rack'
+require './hello.rb'
+require './timing.rb'
+
+use Timing
+run Hello

data/examples/rack_app/hello.rb

@@ -0,0 +1,6 @@
+class Hello
+  def self.call(env)
+    puts "Timing Start: #{env['Timing-Start']}"
+    ['200', {'Content-Type' => 'text/html'}, ['Hello, Rack!']]
+  end
+end

data/examples/rack_app/timing.rb

@@ -0,0 +1,15 @@
+class Timing
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    env['Timing-Start'] = Time.now.to_i
+
+    ts = Time.now
+    status, headers, body = @app.call(env)
+    elapsed_time = Time.now - ts
+    puts "Timing: #{env['REQUEST_METHOD']} #{env['REQUEST_URI']} #{elapsed_time.round(3)}"
+    return [status, headers, body]
+  end
+end

data/lib/meta/api.rb

@@ -0,0 +1,3 @@
+require_relative 'application'
+require_relative 'swagger_doc'
+require_relative 'load_i18n'

data/lib/meta/application/application.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative '../utils/path'
+
+module Meta
+  class Application
+    include Execution::MakeToRackMiddleware
+    include PathMatchingMod.new(path_method: :prefix, matching_mode: :prefix)
+
+    attr_reader :prefix, :mods, :error_guards
+
+    def initialize(prefix: '', mods: [], shared_mods: [], error_guards: [])
+      @prefix = Utils::Path.normalize_path(prefix)
+      @mods = mods
+      @shared_mods = shared_mods
+      @error_guards = error_guards
+    end
+
+    def execute(execution, remaining_path = '')
+      remaining_path_for_children = path_matching.merge_path_params(remaining_path, execution.request)
+
+      @shared_mods.each { |mod| execution.singleton_class.include(mod) }
+
+      mod = find_child_mod(execution, remaining_path_for_children)
+      if mod
+        mod.execute(execution, remaining_path_for_children)
+      else
+        request = execution.request
+        raise Errors::NoMatchingRoute, "未能发现匹配的路由：#{request.request_method} #{request.path}"
+      end
+    rescue StandardError => e
+      guard = error_guards.find { |g| e.is_a?(g[:error_class]) }
+      raise unless guard
+
+      execution.instance_exec(e, &guard[:caller])
+    end
+
+    def match?(execution, remaining_path)
+      return false unless path_matching.match?(remaining_path)
+
+      remaining_path_for_children = path_matching.capture_remaining_part(remaining_path)
+      find_child_mod(execution, remaining_path_for_children) != nil
+    end
+
+    def applications
+      mods.filter { |r| r.is_a?(Application) }
+    end
+
+    def routes
+      mods.filter { |r| r.is_a?(Route) }
+    end
+
+    def to_swagger_doc(options = {})
+      SwaggerDocUtil.generate(self, **options)
+    end
+
+    private
+
+    def find_child_mod(execution, remaining_path_for_children)
+      mods.find { |mod| mod.match?(execution, remaining_path_for_children) }
+    end
+  end
+end

data/lib/meta/application/execution.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require 'rack'
+
+module Meta
+  class Execution
+    attr_reader :request, :response, :params_schema, :request_body_schema
+    attr_accessor :parameters
+
+    def initialize(request)
+      @request = request
+      @response = Rack::Response.new
+      @parameters = {}
+    end
+
+    # 调用方式：
+    #
+    # - `request_body`：等价于 request_body(:keep_missing)
+    # - `request_body(:keep_missing)`
+    # - `request_body(:discard_missing)`
+    def request_body(mode = :keep_missing)
+      @_request_body ||= {}
+
+      case mode
+      when :keep_missing
+        @_request_body[:keep_missing] || @_request_body[:keep_missing] = parse_request_body_for_replacing.freeze
+      when :discard_missing
+        @_request_body[:discard_missing] || @_request_body[:discard_missing] = parse_request_body_for_updating.freeze
+      else
+        raise NameError, "未知的 mode 参数：#{mode}"
+      end
+    end
+
+    # 调用方式：
+    #
+    # - `params`：等价于 params(:keep_missing)
+    # - `params(:keep_missing)`
+    # - `params(:discard_missing)`
+    # - `params(:raw)`
+    def params(mode = :keep_missing)
+      @_params ||= {}
+      return @_params[mode] if @_params.key?(mode)
+
+      if mode == :raw
+        @_params[:raw] = parse_raw_params.freeze
+      else
+        params = parameters
+        params = params.merge(request_body(mode) || {}) if @request_body_schema
+        @_params[mode] = params
+      end
+
+      @_params[mode]
+    end
+
+    # 调用方式：
+    #
+    # - render(value, options?)
+    # - render(key, value, options?)
+    def render(*params)
+      if (params.length < 1 || params.length > 3)
+        raise ArgumentError, "wrong number of arguments (given #{params.length} expected 1..3)"
+      elsif params[0].is_a?(Symbol)
+        key, value, options = params
+      else
+        key = :__root__
+        value, options = params
+      end
+
+      @renders ||= {}
+      @renders[key] = { value: value, options: options || {} }
+    end
+
+    # 运行过程中首先会解析参数
+    def parse_parameters(parameters_meta)
+      self.parameters = parameters_meta.map do |name, options|
+        schema = options[:schema]
+        value = if options[:in] == 'header'
+          schema.filter(request.get_header('HTTP_' + name.to_s.upcase.gsub('-', '_')))
+        else
+          schema.filter(request.params[name.to_s])
+        end
+        [name, value]
+      end.to_h.freeze
+    end
+
+    # REVIEW: parse_params 不再解析参数了，而只是设置 @params_schema，并清理父路由解析的变量
+    def parse_params(params_schema)
+      @params_schema = params_schema
+    end
+
+    def parse_request_body(schema)
+      @request_body_schema = schema
+    end
+
+    def render_entity(entity_schema)
+      # 首先获取 JSON 响应值
+      renders = @renders || {}
+
+      if renders.key?(:__root__) || renders.empty?
+        # 从 root 角度获取
+        if renders[:__root__]
+          hash = renders[:__root__][:value]
+          options = renders[:__root__][:options]
+        else
+          response_body = response.body ? response.body[0] : nil
+          hash = response_body ? JSON.parse(response_body) : {}
+          options = {}
+        end
+
+        new_hash = entity_schema.filter(hash, **options, execution: self, stage: :render)
+        response.body = [JSON.generate(new_hash)]
+      else
+        # 渲染多键值结点
+        new_hash = renders.map do |key, render_content|
+          schema = entity_schema.properties[key]
+          raise Errors::RenderingError, "渲染的键名 `#{key}` 不存在，请检查实体定义以确认是否有拼写错误" if schema.nil?
+
+          filtered = schema.filter(render_content[:value], **render_content[:options], execution: self, stage: :render)
+          [key, filtered]
+        end.to_h
+        response.body = [JSON.generate(new_hash)]
+      end
+    rescue JsonSchema::ValidationErrors => e
+      raise Errors::RenderingInvalid.new(e.errors)
+    end
+
+    private
+
+    def parse_raw_params
+      request_body = request.body.read
+      if request_body.empty?
+        json = {}
+      elsif !request.content_type.start_with?('application/json')
+        raise Errors::UnsupportedContentType, "只接受 Content-Type 为 application/json 的请求参数"
+      else
+        json = JSON.parse(request_body)
+      end
+      json.merge!(request.params) if json.is_a?(Hash)
+
+      request.body.rewind
+      json
+    end
+
+    def parse_request_body_for_replacing
+      begin
+        request_body_schema.filter(params(:raw), stage: :param)
+      rescue JsonSchema::ValidationErrors => e
+        raise Errors::ParameterInvalid.new(e.errors)
+      end
+    end
+
+    def parse_request_body_for_updating
+      begin
+        request_body_schema.filter(params(:raw), stage: :param, discard_missing: true)
+      rescue JsonSchema::ValidationErrors => e
+        raise Errors::ParameterInvalid.new(e.errors)
+      end
+    end
+
+    class Abort < StandardError
+    end
+
+    # 使得能够处理 Execution 的类作为 Rack 中间件
+    module MakeToRackMiddleware
+      def call(env)
+        # 初始化一个执行环境
+        request = Rack::Request.new(env)
+        execution = Execution.new(request)
+
+        execute(execution, request.path)
+
+        response = execution.response
+        response.content_type = 'application/json' unless response.no_content?
+        response.to_a
+      end
+    end
+  end
+end

data/lib/meta/application/meta.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Meta
+  class Meta
+    attr_reader :title, :description, :tags, :parameters, :request_body, :responses
+
+    def initialize(title: nil, description: nil, tags: [], parameters: {}, request_body: nil, responses: nil)
+      @title = title
+      @description = description
+      @tags = tags
+      @parameters = parameters
+      @request_body = request_body
+      @responses = responses || { 204 => nil }
+    end
+
+    def [](key)
+      send(key)
+    end
+
+    def generate_operation_doc(schemas)
+      operation_object = {}
+
+      operation_object[:summary] = title if title
+      operation_object[:tags] = tags unless tags.empty?
+      operation_object[:description] = description if description
+
+      operation_object[:parameters] = parameters.map do |name, options|
+        property_options = options[:schema].param_options
+        {
+          name: name,
+          in: options[:in],
+          required: property_options[:required] || nil,
+          description: property_options[:description] || '',
+          schema: {
+            type: property_options[:type]
+          }
+        }.compact
+      end unless parameters.empty?
+
+      if request_body
+        schema = request_body.to_schema_doc(stage: :param, schemas: schemas)
+        if schema || true
+          operation_object[:requestBody] = {
+            content: {
+              'application/json' => {
+                schema: schema
+              }
+            }
+          }
+        end
+      end
+
+      operation_object[:responses] = responses.transform_values do |schema|
+        {
+          description: '', # description 属性必须存在
+          content: schema ? {
+            'application/json' => {
+              schema: schema.to_schema_doc(stage: :render, schemas: schemas)
+            }
+          } : nil
+        }.compact
+      end unless responses.empty?
+
+      operation_object
+    end
+
+    def self.new(meta = {})
+      meta.is_a?(Meta) ? meta : super(**meta)
+    end
+  end
+end

data/lib/meta/application/path_matching_mod.rb

@@ -0,0 +1,53 @@
+module Meta
+  class PathMatchingMod < Module
+    def initialize(path_method: :path, matching_mode: :full)
+      @path_method = path_method
+      @matching_mode = matching_mode
+    end
+
+    def included(base)
+      path_method = @path_method
+      matching_mode = @matching_mode
+
+      base.class_eval do
+        define_method(:path_matching) do
+          @_path_matching ||= PathMatching.new(send(path_method), matching_mode)
+        end
+      end
+    end
+  end
+
+  class PathMatching
+    def initialize(path_schema, matching_mode)
+      raw_regex = path_schema
+                    .gsub(/:(\w+)/, '(?<\1>[^/]+)')
+                    .gsub(/\*(\w+)/, '(?<\1>.+)')
+                    .gsub(/:/, '[^/]+').gsub('*', '.+')
+      @path_matching_regex = matching_mode == :prefix ? Regexp.new("^#{raw_regex}") : Regexp.new("^#{raw_regex}$")
+    end
+
+    def match?(real_path)
+      @path_matching_regex.match?(real_path)
+    end
+
+    def merge_path_params(path, request)
+      path_params, remaining_path = capture_both(path)
+      path_params.each { |name, value| request.update_param(name, value) }
+      remaining_path
+    end
+
+    def capture_both(real_path)
+      real_path = '' if real_path == '/'
+      m = @path_matching_regex.match(real_path)
+      [m.named_captures, m.post_match]
+    end
+
+    def capture_named_params(real_path)
+      capture_both(real_path)[0]
+    end
+
+    def capture_remaining_part(real_path)
+      capture_both(real_path)[1]
+    end
+  end
+end