meta-api 0.0.8 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b35c78915baab28213ceb9f2b6184c8ae177742ce0524529c681132fa6e0390
-  data.tar.gz: bc4ca96b46e0284f10fa41360ef4308aa7378121ead9f0cd1a536ac027cd590e
+  metadata.gz: 3394a5e2d3b6dfd45f1478d8477426a4a947253d3252a050dc9c1d7cafd3c3d1
+  data.tar.gz: 98d12919b2adf824bec651ba5625076ddb7571962cdc66cee188b3b250fd1b24
 SHA512:
-  metadata.gz: c5cf6b6c1ee9ba5af2826b6682e57a357bbd74caf7807a5f3f9cbd124b99bdce4bcc7cba7040b45b2c1d62b9abfda1e4ee6c47853c2ebcb57bfd2d8a224db622
-  data.tar.gz: 5043cc4c8516d7c6bc827d32889e26a2164299ba0a71b1439bd1594aabdd1975bbd1994139fed2ffca93409e9c1f2118157301b3cef502767750c52b061c7367
+  metadata.gz: c1e80fecb3cf0bce148345660f19a8f44136b1e1647471e89aa9fb4d1c4f55a0ddf7ccb11fdc26ca7880c318173ed4f3254e0835d5bfd96e77048a301804d729
+  data.tar.gz: 16d7fdf0f82b89155eb0fc655e424d54ba5bf880c984dd322266afdb2952c4c34ff1ce2c83f8d174adcb086057d6c63aa7534b75defd4c3f7ff84f8a7f948ec0

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 更新日志
 
+## 0.0.9（2023 年 7 月 22 日）
+
+1. JsonSchema 添加 before:、after: 选项，用于在过滤前后执行一些操作。
+2. 新添加一个 if: 选项用在属性上，它能够作为一个条件，当条件为 false 时，该属性不会被包含在结果内。
+3. 属性的 scope: 选项改名为 on: 选项。
+4. MetaBuilder 添加一个 scope 宏。
+5. Meta.config 的 JsonSchema 相关配置项改名。
+6. 优化异常的捕获。
+
+## 0.0.8（2023 年 7 月 17 日）
+
+1. `Meta.config` 添加 `initialize_configuration` 方法，用于接受若干个 Hash 初始化配置。
+2. 修复 GET 请求下会将 `header` 参数覆盖为 `query` 参数的 bug.
+
 ## 0.0.7（2023 年 7 月 14 日）
 
 1. 定义 parameters 宏时能够自动识别 `path` 参数。

data/lib/meta/application/execution.rb

@@ -4,8 +4,8 @@ require 'rack'
 
 module Meta
   class Execution
-    attr_reader :request, :response, :params_schema, :request_body_schema
-    attr_accessor :parameters
+    attr_reader :request, :response
+    attr_accessor :route_meta
 
     def initialize(request)
       @request = request
@@ -13,6 +13,10 @@ module Meta
       @parameters = {}
     end
 
+    def parameters
+      @_parameters || @_parameters = route_meta.parse_parameters(self)
+    end
+
     # 调用方式：
     #
     # - `request_body`：等价于 request_body(:keep_missing)
@@ -23,9 +27,9 @@ module Meta
 
       case mode
       when :keep_missing
-        @_request_body[:keep_missing] || @_request_body[:keep_missing] = parse_request_body_for_replacing.freeze
+        @_request_body[:keep_missing] || @_request_body[:keep_missing] = route_meta.parse_request_body(self).freeze
       when :discard_missing
-        @_request_body[:discard_missing] || @_request_body[:discard_missing] = parse_request_body_for_updating.freeze
+        @_request_body[:discard_missing] || @_request_body[:discard_missing] = route_meta.parse_request_body(self, discard_missing: true).freeze
       else
         raise NameError, "未知的 mode 参数：#{mode}"
       end
@@ -45,7 +49,7 @@ module Meta
         @_params[:raw] = parse_raw_params.freeze
       else
         params = parameters
-        params = params.merge(request_body(mode) || {}) if @request_body_schema
+        params = params.merge(request_body(mode) || {}) if route_meta.request_body
         @_params[mode] = params
       end
 
@@ -67,16 +71,14 @@ module Meta
       end
 
       @renders ||= {}
-      @renders[key] = { value: value, options: options || {} }
-    end
-
-    # 运行过程中首先会解析参数
-    def parse_parameters(parameters_meta)
-      self.parameters = parameters_meta.filter(request).freeze
-    end
+      raise '同一种 render 方式只能调用一次，请检查是否重复使用相同的 key 渲染，或者重复调用 render(value) 的方式' if @renders.key?(key)
+      if key == :__root__ && @renders.keys.any? { |key| key != :__root__ }
+        raise '已使用 render(:key, value) 的方式调用过，不能再使用 render(value) 的方式'
+      elsif key != :__root__ && @renders.key?(:__root__)
+        raise '已使用 render(value) 的方式调用过，不能再使用 render(:key, value) 的方式'
+      end
 
-    def parse_request_body(schema)
-      @request_body_schema = schema
+      @renders[key] = { value: value, options: options || {} }
     end
 
     def render_entity(entity_schema)
@@ -94,12 +96,7 @@ module Meta
           options = {}
         end
 
-        new_hash = entity_schema.filter(hash,
-          **Meta.config.json_schema_user_options,
-          **Meta.config.json_schema_render_stage_options,
-          **options,
-          execution: self, stage: :render
-        )
+        new_hash = route_meta.render_entity(self, entity_schema, hash, options)
         response.content_type = 'application/json' if response.content_type.nil?
         response.body = [JSON.generate(new_hash)]
       else
@@ -108,13 +105,8 @@ module Meta
         final_value = {}
         renders.each do |key, render_content|
           raise Errors::RenderingError, "渲染的键名 `#{key}` 不存在，请检查实体定义以确认是否有拼写错误" unless entity_schema.properties.key?(key)
-          schema = entity_schema.properties[key].schema(:render)
-          final_value[key] = schema.filter(render_content[:value],
-            **Meta.config.json_schema_user_options,
-            **Meta.config.json_schema_render_stage_options,
-            **render_content[:options],
-            execution: self, stage: :render
-          )
+          schema = entity_schema.properties[key].staged(:render)
+          final_value[key] = route_meta.render_entity(self, schema, render_content[:value], render_content[:options])
         rescue JsonSchema::ValidationErrors => e
           # 错误信息再度绑定 key
           errors.merge! e.errors.transform_keys! { |k| k.empty? ? key : "#{key}.#{k}" }
@@ -152,28 +144,6 @@ module Meta
       json
     end
 
-    def parse_request_body_for_replacing
-      request_body_schema.filter(
-        params(:raw),
-        **Meta.config.json_schema_user_options,
-        **Meta.config.json_schema_param_stage_options,
-        execution: self, stage: :param
-      )
-    rescue JsonSchema::ValidationErrors => e
-      raise Errors::ParameterInvalid.new(e.errors)
-    end
-
-    def parse_request_body_for_updating
-      request_body_schema.filter(
-        params(:raw),
-        **Meta.config.json_schema_user_options,
-        **Meta.config.json_schema_param_stage_options,
-        execution: self, stage: :param, discard_missing: true
-      )
-    rescue JsonSchema::ValidationErrors => e
-      raise Errors::ParameterInvalid.new(e.errors)
-    end
-
     class Abort < Exception
     end
 

data/lib/meta/application/metadata.rb

@@ -1,24 +1,84 @@
 # frozen_string_literal: true
+
 require_relative 'parameters'
 
 module Meta
   class Metadata
-    attr_reader :title, :description, :tags, :parameters, :request_body, :responses
+    module ExecutionMethods
+      def parse_parameters(execution)
+        parameters.filter(execution.request)
+        # TODO: 未捕获 JsonSchema::ValidationErrors 异常
+      end
+
+      def parse_request_body(execution, discard_missing: false)
+        method = execution.request.request_method.downcase.to_sym
+        request_body.filter(
+          execution.params(:raw),
+          **Meta.config.json_schema_user_options,
+          **Meta.config.json_schema_param_stage_user_options,
+          **{ execution: execution, stage: :param, scope: @scope.concat([method]), discard_missing: discard_missing }.compact
+        )
+      rescue JsonSchema::ValidationErrors => e
+        raise Errors::ParameterInvalid.new(e.errors)
+      end
+
+      def render_entity(execution, entity_schema, value, user_options)
+        method = execution.request.request_method.downcase.to_sym
+        entity_schema.filter(value,
+          **Meta.config.json_schema_user_options,
+          **Meta.config.json_schema_render_stage_user_options,
+          **{ execution: execution, stage: :render, scope: @scope.concat([method]) }.compact,
+          **user_options,
+        )
+      end
+
+      def set_response(execution)
+        set_status(execution)
+        render_response_body(execution) if self.responses
+      end
+
+      private
+
+      def set_status(execution)
+        response_definitions = self.responses
+        response = execution.response
+        if response.status == 0
+          response.status = (response_definitions&.length > 0) ? response_definitions.keys[0] : 200
+        end
+      end
+
+      def render_response_body(execution)
+        response_definitions = self[:responses]
+        return if response_definitions.empty? # 未设定 status 宏时不需要执行 render_entity 方法
+
+        # 查找 entity schema
+        entity_schema = response_definitions[execution.response.status]
+        return if entity_schema.nil?
+
+        # 执行面向 schema 的渲染
+        execution.render_entity(entity_schema)
+      end
+    end
+
+    include ExecutionMethods
+
+    attr_reader :title, :description, :tags, :parameters, :request_body, :responses, :scope
 
-    def initialize(title: nil, description: nil, tags: [], parameters: {}, request_body: nil, responses: nil)
+    def initialize(title: nil, description: nil, tags: [], parameters: {}, request_body: nil, responses: nil, scope: nil)
       @title = title
       @description = description
       @tags = tags
       @parameters = parameters.is_a?(Parameters) ? parameters : Parameters.new(parameters)
       @request_body = request_body
       @responses = responses || {} # || { 204 => nil }
+      @scope = scope
     end
 
     def [](key)
       send(key)
     end
 
-    def generate_operation_doc(schemas)
+    def generate_operation_doc(schemas, scope: [])
       operation_object = {}
 
       operation_object[:summary] = title if title
@@ -28,7 +88,7 @@ module Meta
       operation_object[:parameters] = parameters.to_swagger_doc
 
       if request_body
-        schema = request_body.to_schema_doc(stage: :param, schemas: schemas)
+        schema = request_body.to_schema_doc(stage: :param, scope: self.scope + scope, schemas: schemas)
         if schema || true
           operation_object[:requestBody] = {
             content: {
@@ -45,7 +105,7 @@ module Meta
           description: '', # description 属性必须存在
           content: schema ? {
             'application/json' => {
-              schema: schema.to_schema_doc(stage: :render, schemas: schemas)
+              schema: schema.to_schema_doc(stage: :render, scope: self.scope + scope, schemas: schemas)
             }
           } : nil
         }.compact

data/lib/meta/application/route.rb

@@ -21,13 +21,9 @@ module Meta
     def execute(execution, remaining_path)
       path_matching.merge_path_params(remaining_path, execution.request)
 
-      execution.parse_parameters(@meta[:parameters]) if @meta[:parameters]
-      execution.parse_request_body(@meta[:request_body]) if @meta[:request_body]
-
+      execution.route_meta = @meta # 解析参数的准备
       action.execute(execution) if action
-
-      set_status(execution)
-      render_entity(execution) if @meta[:responses]
+      @meta.set_response(execution) if @meta.responses
     rescue Execution::Abort
       execution.response.status = 200 if execution.response.status == 0
     end
@@ -42,26 +38,8 @@ module Meta
       return true
     end
 
-    private
-
-    def set_status(execution)
-      response_definitions = @meta[:responses]
-      response = execution.response
-      if response.status == 0
-        response.status = (response_definitions&.length > 0) ? response_definitions.keys[0] : 200
-      end
-    end
-
-    def render_entity(execution)
-      response_definitions = @meta[:responses]
-      return if response_definitions.empty? # 未设定 status 宏时不需要执行 render_entity 方法
-
-      # 查找 entity schema
-      entity_schema = response_definitions[execution.response.status]
-      return if entity_schema.nil?
-
-      # 执行面向 schema 的渲染
-      execution.render_entity(entity_schema)
+    def generate_operation_doc(schemas)
+      meta.generate_operation_doc(schemas, scope: [method])
     end
   end
 end

data/lib/meta/config.rb

@@ -6,8 +6,8 @@ module Meta
   DEFAULT_OPTIONS = {
     default_locked_scope: nil,
     json_schema_user_options: {},
-    json_schema_param_stage_options: {},
-    json_schema_render_stage_options: {}
+    json_schema_param_stage_user_options: {},
+    json_schema_render_stage_user_options: {}
   }
 
   class << self

data/lib/meta/json_schema/builders/schema_builder_tool.rb

@@ -4,6 +4,7 @@ require_relative 'ref_schema_builder'
 require_relative 'dynamic_schema_builder'
 require_relative 'array_schema_builder'
 require_relative 'object_schema_builder'
+require_relative '../schemas/staging_schema'
 
 module Meta
   module JsonSchema
@@ -33,7 +34,7 @@ module Meta
           elsif apply_object_schema?(options, block)
             ObjectSchemaBuilder.new(options, &block).to_schema
           else
-            BaseSchema.new(options)
+            StagingSchema.build_from_options(options)
           end
         end
 

data/lib/meta/json_schema/schemas/array_schema.rb

@@ -11,20 +11,6 @@ module Meta
         @items = items
       end
 
-      def filter(array_value, options = {})
-        array_value = super(array_value, options)
-        return nil if array_value.nil?
-        raise ValidationError.new('参数应该传递一个数组') unless array_value.respond_to?(:each_with_index)
-
-        array_value.each_with_index.map do |item, index|
-          begin
-            @items.filter(item, **options)
-          rescue ValidationErrors => e
-            raise e.prepend_root("[#{index}]")
-          end
-        end
-      end
-
       def to_schema_doc(**user_options)
         stage_options = options
 
@@ -35,6 +21,19 @@ module Meta
         schema[:description] = stage_options[:description] if stage_options[:description]
         schema
       end
+
+      private
+
+      def filter_internal(array_value, user_options)
+        raise ValidationError.new('参数应该传递一个数组') unless array_value.respond_to?(:each_with_index)
+        array_value.each_with_index.map do |item, index|
+          begin
+            @items.filter(item, user_options)
+          rescue ValidationErrors => e
+            raise e.prepend_root("[#{index}]")
+          end
+        end
+      end
     end
   end
 end

data/lib/meta/json_schema/schemas/base_schema.rb

@@ -5,11 +5,35 @@ require_relative '../support/schema_options'
 
 module Meta
   module JsonSchema
+    # 表示一个基本类型的 Schema，或继承自该类表示一个拥有其他扩展能力的 Schema.
+    #
+    # 该类包含了通用 JsonSchema 思维的基本逻辑，比如 stage 和 scope. 其他 Schema 类应当主动地继
+    # 承自该类，这样就会自动获得 stage 和 scope 的能力。
+    #
+    # 该类剩余的逻辑是提供一个 `options` 属性，用于描述该 Schema. 因此，直接实例化该类可以用于表示
+    # 基本类型，而继承该类可以用于表示还有内部递归处理的对象和数组类型。这时，应当在子类的构造函数中调
+    # 用父类的构造方法，以便初始化 `options` 属性。并且在子类中重写 `filter_internal` 方法，实现
+    # 内部递归处理的逻辑。这种模式的案例主要是 `ObjectSchema` 和 `ArraySchema`.
+    #
+    # 如果是组合模式，也应当继承自该类，以便获得 stage 和 scope 的能力。但是，组合模式的 `options`
+    # 调用是非法的，因此不应当在构造函数中调用父类的构造方法。此时 options 为 nil，这样用到 options
+    # 的地方都会抛出异常（NoMethodError: undefined method `[]' for nil:NilClass）。这种模式
+    # 的案例很多，包括 StagingSchema、RefSchema 等。
     class BaseSchema
       OPTIONS_CHECKER = Utils::KeywordArgs::Builder.build do
         key :type, :items, :description, :presenter, :value, :default, :properties, :convert
         key :validate, :required, :format, :allowable
-        key :param, :render
+        key :before, :after
+        key :if
+      end
+
+      USER_OPTIONS_CHECKER = Utils::KeywordArgs::Builder.build do
+        key :execution, :object_value, :type_conversion, :validation, :user_data
+        key :stage, validator: ->(value) { raise ArgumentError, "stage 只能取值为 :param 或 :render" unless [:param, :render].include?(value) }
+
+        # 以下是 ObjectSchema 需要的选项
+        # extra_properties 只能取值为 :ignore、:raise_error
+        key :discard_missing, :extra_properties, :exclude, :scope
       end
 
       # `options` 包含了转换器、验证器、文档、选项。
@@ -22,25 +46,22 @@ module Meta
       attr_reader :options
 
       def initialize(options = {})
+        raise ArgumentError, 'options 必须是 Hash 类型' unless options.is_a?(Hash)
         options = OPTIONS_CHECKER.check(options)
         raise '不允许 BaseSchema 直接接受 array 类型，必须通过继承使用 ArraySchema' if options[:type] == 'array' && self.class == BaseSchema
 
         @options = SchemaOptions.normalize(options).freeze
       end
 
-      USER_OPTIONS_CHECKER = Utils::KeywordArgs::Builder.build do
-        key :execution, :object_value, :type_conversion, :validation, :user_data
-        key :stage, validator: ->(value) { raise ArgumentError, "stage 只能取值为 :param 或 :render" unless [:param, :render].include?(value) }
-
-        # 以下是 ObjectSchema 需要的选项
-        # extra_properties 只能取值为 :ignore、:raise_error
-        key :discard_missing, :extra_properties, :exclude, :scope
+      def filter?
+        true
       end
 
       def filter(value, user_options = {})
         user_options = USER_OPTIONS_CHECKER.check(user_options)
 
-        value = resolve_value(user_options) if options[:value]
+        value = value_callback(user_options) if options[:value]
+        value = before_callback(value, user_options) if options[:before]
         value = JsonSchema::Presenters.present(options[:presenter], value) if options[:presenter]
         value = resolve_default_value(options[:default]) if value.nil? && options.key?(:default)
         value = options[:convert].call(value) if options[:convert]
@@ -59,30 +80,45 @@ module Meta
         # 第二步，做校验。
         validate!(value, options) unless user_options[:validation] == false
 
+        # 第三步，如果存在内部属性，递归调用。
+        value = filter_internal(value, user_options) unless value.nil?
+
+        # 最后，返回 value
+        value = after_callback(value, user_options) if options[:after]
         value
       end
 
-      def value?
-        options[:value] != nil
+      # 返回能够处理 scope 和 stage 的 schema（可以是 self），否则应返回 UnsupportedStageSchema 或 nil.
+      def find_schema(scope:, stage:)
+        staged(stage)&.scoped(scope)
       end
 
-      def resolve_value(user_options)
-        value_proc = options[:value]
-        if value_proc.lambda?
-          value_proc_params = []
-          value_proc_params << user_options[:object_value] if value_proc.arity >= 1
-          value_proc_params << user_options[:user_data] if value_proc.arity >= 2
-        else
-          value_proc_params = [user_options[:object_value], user_options[:user_data]]
-        end
+      # 返回能够处理 stage 的 schema（可以是 self），否则返回 UnsupportedStageSchema.
+      def staged(stage)
+        self
+      end
 
-        if user_options[:execution]
-          user_options[:execution].instance_exec(*value_proc_params, &value_proc)
+      # 返回能够处理 scope 的 schema（可以是 self），否则返回 nil.
+      def scoped(scope)
+        self
+      end
+
+      # 执行 if: 选项，返回 true 或 false
+      def if?(user_options)
+        return true if options[:if].nil?
+
+        execution = user_options[:execution]
+        if execution
+          execution.instance_exec(&options[:if])
         else
-          value_proc.call(*value_proc_params)
+          options[:if]&.call
         end
       end
 
+      def value?
+        options[:value] != nil
+      end
+
       # 生成 Swagger 文档的 schema 格式。
       #
       # 选项：
@@ -106,22 +142,51 @@ module Meta
 
       private
 
-        def validate!(value, stage_options)
-          stage_options.each do |key, option|
-            validator = JsonSchema::Validators[key]
-            validator&.call(value, option, stage_options)
-          end
+      def validate!(value, stage_options)
+        stage_options.each do |key, option|
+          validator = JsonSchema::Validators[key]
+          validator&.call(value, option, stage_options)
         end
+      end
 
-        def resolve_default_value(default_resolver)
-          if default_resolver.respond_to?(:call)
-            default_resolver.call
-          elsif default_resolver.respond_to?(:dup)
-            default_resolver.dup
-          else
-            default_resolver
-          end
+      def resolve_value(value, user_options, value_proc, arguments)
+        if value_proc.lambda?
+          value_proc_params = arguments[0...value_proc.arity]
+        else
+          value_proc_params = arguments
+        end
+        if user_options[:execution]
+          user_options[:execution].instance_exec(*value_proc_params, &value_proc)
+        else
+          value_proc.call(*value_proc_params)
         end
+      end
+
+      def resolve_default_value(default_resolver)
+        if default_resolver.respond_to?(:call)
+          default_resolver.call
+        elsif default_resolver.respond_to?(:dup)
+          default_resolver.dup
+        else
+          default_resolver
+        end
+      end
+
+      def filter_internal(value, user_options)
+        value
+      end
+
+      def value_callback(user_options)
+        resolve_value(nil, user_options, options[:value], [user_options[:object_value], user_options[:user_data]])
+      end
+
+      def before_callback(value, user_options)
+        resolve_value(value, user_options, options[:before], [value, user_options[:object_value], user_options[:user_data]])
+      end
+
+      def after_callback(value, user_options)
+        resolve_value(value, user_options, options[:after], [value, user_options[:object_value], user_options[:user_data]])
+      end
     end
   end
 end

data/lib/meta/json_schema/schemas/object_schema.rb

@@ -38,13 +38,9 @@ module Meta
 
       def filter(object_value, user_options = {})
         # 合并 user_options
-        user_options = user_options.merge(locked_options) if locked_options
         user_options = USER_OPTIONS_CHECKER.check(user_options)
-
-        object_value = super(object_value, user_options)
-
-        return nil if object_value.nil?
-        @properties.filter(object_value, user_options)
+        user_options = merge_user_options(user_options, locked_options) if locked_options
+        super
       end
 
       # 合并其他的属性，并返回一个新的 ObjectSchema
@@ -57,13 +53,14 @@ module Meta
         @schema_name_resolver.call(stage, locked_scopes)
       end
 
-      def to_schema_doc(stage: nil, **user_options)
-        locked_scopes = (locked_options || {})[:scope] || []
+      def to_schema_doc(user_options = {})
+        user_options = USER_OPTIONS_CHECKER.check(user_options)
+        user_options = merge_user_options(user_options, locked_options) if locked_options
 
         schema = { type: 'object' }
         schema[:description] = options[:description] if options[:description]
 
-        properties, required_keys = @properties.to_swagger_doc(stage: stage, locked_scopes: locked_scopes, **user_options)
+        properties, required_keys = @properties.to_swagger_doc(**user_options)
         schema[:properties] = properties unless properties.empty?
         schema[:required] = required_keys unless required_keys.empty?
         schema
@@ -76,6 +73,22 @@ module Meta
       def locked_exclude
         locked_options && locked_options[:exclude]
       end
+
+      private
+
+      def filter_internal(object_value, user_options)
+        @properties.filter(object_value, user_options)
+      end
+
+      def merge_user_options(user_options, locked_options)
+        user_options.merge(locked_options) do |key, user_value, locked_value|
+          if key == :scope
+            user_value + locked_value
+          else
+            locked_value
+          end
+        end
+      end
     end
   end
 end