meta-api 0.0.5 → 0.0.7

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

@@ -171,3 +171,13 @@ end
 ```
 
 面对这两种使用方式，有何使用上的建议呢？我的建议是，你习惯用哪种就用哪种。
+
+## `JsonSchema#filter` 方法的用户选项
+
+### `discard_missing:`
+
+规定是否忽略缺失的属性。所谓缺失的属性，是指在 `ObjectSchema` 实体宏中定义，但数据中不包含这个键值的属性。你可以将 `discard_missing: true` 视为 HTTP Patch 方法，`discard_missing: false` 视为 HTTP Put 方法。
+
+### `extra_properties:`
+
+规定多余的属性的处理办法。所谓多余的属性，是指未在 `ObjectSchema`  实体宏中定义，但数据中依然存在这个键值的属性。一般来讲我们允许前端传递一些多余的属性，但可能在内部测试时设定为更严格的条件。

data/examples/rails_app/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: /home/run/workspace/personal/web-frame
   specs:
-    meta-api (0.0.4)
+    meta-api (0.0.6)
 
 GEM
   remote: https://gems.ruby-china.com/

data/lib/meta/application/execution.rb

@@ -9,7 +9,7 @@ module Meta
 
     def initialize(request)
       @request = request
-      @response = Rack::Response.new
+      @response = Rack::Response.new([], 0) # 状态码初始为 0，代表一个未设置状态
       @parameters = {}
     end
 
@@ -75,11 +75,6 @@ module Meta
       self.parameters = parameters_meta.filter(request).freeze
     end
 
-    # parse_params 不再解析参数了，而只是设置 @params_schema，并清理父路由解析的变量
-    def parse_params(params_schema)
-      @params_schema = params_schema
-    end
-
     def parse_request_body(schema)
       @request_body_schema = schema
     end
@@ -99,23 +94,47 @@ module Meta
           options = {}
         end
 
-        new_hash = entity_schema.filter(hash, **options, execution: self, stage: :render, validation: ::Meta.config.render_validation, type_conversion: ::Meta.config.render_type_conversion)
+        new_hash = entity_schema.filter(hash,
+          **Meta.config.json_schema_user_options,
+          **Meta.config.json_schema_render_stage_options,
+          **options,
+          execution: self, stage: :render
+        )
+        response.content_type = 'application/json' if response.content_type.nil?
         response.body = [JSON.generate(new_hash)]
       else
         # 渲染多键值结点
-        new_hash = renders.map do |key, render_content|
+        errors = {}
+        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)
-
-          filtered = schema.filter(render_content[:value], **render_content[:options], execution: self, stage: :render)
-          [key, filtered]
+          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
+          )
+        rescue JsonSchema::ValidationErrors => e
+          # 错误信息再度绑定 key
+          errors.merge! e.errors.transform_keys! { |k| k.empty? ? key : "#{key}.#{k}" }
         end.to_h
-        response.body = [JSON.generate(new_hash)]
+
+        if errors.empty?
+          response.content_type = 'application/json' if response.content_type.nil?
+          response.body = [JSON.generate(final_value)]
+        else
+          raise Errors::RenderingInvalid.new(errors)
+        end
       end
     rescue JsonSchema::ValidationErrors => e
       raise Errors::RenderingInvalid.new(e.errors)
     end
 
+    def abort_execution!
+      raise Abort
+    end
+
     private
 
     def parse_raw_params
@@ -134,22 +153,28 @@ module Meta
     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
+      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
-      begin
-        request_body_schema.filter(params(:raw), stage: :param, discard_missing: true)
-      rescue JsonSchema::ValidationErrors => e
-        raise Errors::ParameterInvalid.new(e.errors)
-      end
+      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 < StandardError
+    class Abort < Exception
     end
 
     # 使得能够处理 Execution 的类作为 Rack 中间件
@@ -162,7 +187,6 @@ module Meta
         execute(execution, request.path)
 
         response = execution.response
-        response.content_type = 'application/json' unless response.no_content?
         response.to_a
       end
     end

data/lib/meta/application/linked_action.rb

@@ -3,16 +3,14 @@
 # 洋葱圈模型的链式调用，需要结合 Meta::RouteDSL::AroundActionBuilder 才可以看到它奇效。
 
 module Meta
-  module RouteDSL
-    class LinkedAction
-      def initialize(current_proc, next_action)
-        @current_proc = current_proc
-        @next_action = next_action
-      end
+  class LinkedAction
+    def initialize(current_proc, next_action)
+      @current_proc = current_proc
+      @next_action = next_action
+    end
 
-      def execute(execution)
-        execution.instance_exec(@next_action, &@current_proc)
-      end
+    def execute(execution)
+      execution.instance_exec(@next_action, &@current_proc)
     end
   end
 end

data/lib/meta/application/metadata.rb

@@ -11,7 +11,7 @@ module Meta
       @tags = tags
       @parameters = parameters.is_a?(Parameters) ? parameters : Parameters.new(parameters)
       @request_body = request_body
-      @responses = responses || { 204 => nil }
+      @responses = responses || {} # || { 204 => nil }
     end
 
     def [](key)
@@ -54,8 +54,10 @@ module Meta
       operation_object.compact
     end
 
-    def self.new(meta = {})
-      meta.is_a?(Metadata) ? meta : super(**meta)
+    class << self
+      def new(meta = {})
+        meta.is_a?(Metadata) ? meta : super(**meta)
+      end
     end
   end
 end

data/lib/meta/application/parameters.rb

@@ -7,19 +7,27 @@ module Meta
     attr_reader :parameters
 
     def initialize(parameters)
-      @parameters = parameters
+      @parameters = parameters.dup
     end
 
     def filter(request)
-      parameters.map do |name, options|
+      errors = {}
+      final_value = {}
+
+      parameters.each 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
+                  schema.filter(request.get_header('HTTP_' + name.to_s.upcase.gsub('-', '_')))
+                else
+                  schema.filter(request.params[name.to_s])
+                end
+        final_value[name] = value
+      rescue JsonSchema::ValidationError => e
+        errors[name] = e.message
+      end
+      raise Errors::ParameterInvalid.new(errors) unless errors.empty?
+
+      final_value
     end
 
     def to_swagger_doc

data/lib/meta/application/route.rb

@@ -10,6 +10,7 @@ module Meta
 
     attr_reader :path, :method, :meta, :action
 
+    # path 是局部 path，不包含由父级定义的前缀
     def initialize(path: '', method: :all, meta: {}, action: nil)
       @path = Utils::Path.normalize_path(path)
       @method = method
@@ -20,16 +21,15 @@ module Meta
     def execute(execution, remaining_path)
       path_matching.merge_path_params(remaining_path, execution.request)
 
-      begin
-        execution.parse_parameters(@meta[:parameters]) if @meta[:parameters]
-        execution.parse_request_body(@meta[:request_body]) if @meta[:request_body]
+      execution.parse_parameters(@meta[:parameters]) if @meta[:parameters]
+      execution.parse_request_body(@meta[:request_body]) if @meta[:request_body]
 
-        action.execute(execution) if action
+      action.execute(execution) if action
 
-        render_entity(execution) if @meta[:responses]
-      rescue Execution::Abort
-        execution
-      end
+      set_status(execution)
+      render_entity(execution) if @meta[:responses]
+    rescue Execution::Abort
+      execution.response.status = 200 if execution.response.status == 0
     end
 
     def match?(execution, remaining_path)
@@ -44,14 +44,24 @@ module Meta
 
     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)
-      responses = @meta[:responses]
-      status = execution.response.status
-      codes = responses.keys
-      return unless codes.include?(status)
+      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?
 
-      entity_schema = responses[status]
-      execution.render_entity(entity_schema) if entity_schema
+      # 执行面向 schema 的渲染
+      execution.render_entity(entity_schema)
     end
   end
 end

data/lib/meta/config.rb

@@ -2,11 +2,16 @@
 
 module Meta
   class Config
-    attr_accessor :render_validation, :render_type_conversion
+    attr_accessor :default_locked_scope,
+                  :json_schema_user_options,
+                  :json_schema_param_stage_options,
+                  :json_schema_render_stage_options
 
     def initialize
-      @render_type_conversion = true
-      @render_validation = true
+      @default_locked_scope = nil
+      @json_schema_user_options = {}
+      @json_schema_param_stage_options = {}
+      @json_schema_render_stage_options = {}
     end
   end
 

data/lib/meta/errors.rb

@@ -13,7 +13,7 @@ module Meta
     end
 
     class RenderingInvalid < JsonSchema::ValidationErrors
-      def initialize(errors)
+      def initialize(errors = {})
         super(errors, "渲染实体异常：#{errors}")
       end
     end

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

@@ -12,7 +12,13 @@ module Meta
         SCHEMA_BUILDER_OPTIONS = Utils::KeywordArgs::Builder.build do
           permit_extras true
 
-          key :ref, alias_names: [:using]
+          key :ref, alias_names: [:using], normalizer: ->(entity) {
+            if Meta.config.default_locked_scope && entity.is_a?(Class) && entity < Meta::Entity
+              entity.locked(scope: Meta.config.default_locked_scope)
+            else
+              entity
+            end
+          }
           key :dynamic_ref, alias_names: [:dynamic_using], normalizer: ->(value) { value.is_a?(Proc) ? { resolve: value } : value }
         end
         def build(options = {}, &block)
@@ -34,7 +40,7 @@ module Meta
         private
 
         def apply_array_schema?(options, block)
-          options[:type] == 'array' && (options[:items] || options[:ref] || options[:dynamic_ref] || block)
+          options[:type] == 'array'
         end
 
         def apply_object_schema?(options, block)

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

@@ -23,14 +23,18 @@ module Meta
 
       def initialize(options = {})
         options = OPTIONS_CHECKER.check(options)
-        @options = SchemaOptions.normalize(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 :stage, :execution, :object_value, :type_conversion, :validation, :user_data
+        key :execution, :object_value, :type_conversion, :validation, :user_data
+        key :stage, validator: ->(value) { raise ArgumentError, "stage 只能取值为 :param 或 :render" unless [:param, :render].include?(value) }
 
-        # 以下三个是 ObjectSchema 需要的选项
-        key :discard_missing, :exclude, :scope
+        # 以下是 ObjectSchema 需要的选项
+        # extra_properties 只能取值为 :ignore、:raise_error
+        key :discard_missing, :extra_properties, :exclude, :scope
       end
 
       def filter(value, user_options = {})
@@ -38,7 +42,7 @@ module Meta
 
         value = resolve_value(user_options) if options[:value]
         value = JsonSchema::Presenters.present(options[:presenter], value) if options[:presenter]
-        value = options[:default] if value.nil? && options.key?(:default)
+        value = resolve_default_value(options[:default]) if value.nil? && options.key?(:default)
         value = options[:convert].call(value) if options[:convert]
 
         # 第一步，转化值。
@@ -108,6 +112,16 @@ module Meta
             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
+        end
     end
   end
 end

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

@@ -48,7 +48,7 @@ module Meta
       end
 
       # 合并其他的属性，并返回一个新的 ObjectSchema
-      def merge(properties)
+      def merge_other_properties(properties)
         ObjectSchema.new(properties: self.properties.merge(properties))
       end
 

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

@@ -92,7 +92,7 @@ module Meta
         object = {}
         errors = {}
         filtered_properties.each do |name, property_schema|
-          value = resolve_property_value(object_value, name, property_schema, stage)
+          value = resolve_property_value(object_value, name, property_schema)
 
           begin
             object[name] = property_schema.filter(value, **user_options, object_value: object_value)
@@ -101,6 +101,11 @@ module Meta
           end
         end.to_h
 
+        # 第三步，检测是否有剩余的属性
+        if user_options[:extra_properties] == :raise_error && !(object_value.keys.map(&:to_sym) - properties.keys).empty?
+          raise JsonSchema::ValidationError, '遇到多余的属性'
+        end
+
         if errors.empty?
           object
         else
@@ -122,6 +127,10 @@ module Meta
       # 程序中有些地方用到了这三个方法
       def_delegators :@properties, :empty?, :key?, :[]
 
+      def merge(properties)
+        self.class.new(@properties.merge(properties.instance_eval { @properties }))
+      end
+
       def self.build_property(*args)
         StagingProperty.build(*args)
       end
@@ -143,7 +152,7 @@ module Meta
         end
       end
 
-      def resolve_property_value(object_value, name, property_schema, stage)
+      def resolve_property_value(object_value, name, property_schema)
         if property_schema.value?
           nil
         elsif object_value.is_a?(Hash) || object_value.is_a?(ObjectWrapper)

data/lib/meta/json_schema/support/type_converter.rb

@@ -96,9 +96,9 @@ module Meta
       @object_converters = {
         [Object] => lambda do |value|
           if [TrueClass, FalseClass, Integer, Float, String].any? { |ruby_type| value.is_a?(ruby_type) }
-            raise TypeConvertError, I18n.t(:'json_schema.errors.type_convert.object', value: value, real_type: I18n.t(:'json_schema.type_description.basic'))
+            raise TypeConvertError, I18n.t(:'json_schema.errors.type_convert.object', value: value, real_type: I18n.t(:'json_schema.type_names.basic'))
           elsif value.is_a?(Array)
-            raise TypeConvertError, I18n.t(:'json_schema.errors.type_convert.object', value: value, real_type: I18n.t(:'json_schema.type_description.array'))
+            raise TypeConvertError, I18n.t(:'json_schema.errors.type_convert.object', value: value, real_type: I18n.t(:'json_schema.type_names.array'))
           end
 
           ObjectWrapper.new(value)

data/lib/meta/json_schema/support/validators.rb

@@ -28,7 +28,7 @@ module Meta
         },
         allowable: proc { |value, allowable_values|
           next if value.nil?
-          raise JsonSchema::ValidationError, I18n.t(:'json_schema.errors.allowable') unless allowable_values.include?(value)
+          raise JsonSchema::ValidationError, I18n.t(:'json_schema.errors.allowable', allowable_values: allowable_values) unless allowable_values.include?(value)
         }
       }
 

data/lib/meta/route_dsl/application_builder.rb

@@ -2,39 +2,36 @@
 
 require_relative 'route_builder'
 require_relative 'meta_builder'
+require_relative '../utils/route_dsl_builders'
 
 module Meta
   module RouteDSL
     class ApplicationBuilder
       include MetaBuilder::Delegator
 
-      def initialize(prefix = nil, &block)
-        @mod_prefix = prefix
+      def initialize(full_prefix = '/', &block)
+        @full_prefix = full_prefix
         @callbacks = []
         @error_guards = []
-        @meta_builder = MetaBuilder.new
+        @meta_builder = MetaBuilder.new(route_full_path: full_prefix)
         @mod_builders = []
         @shared_mods = []
 
         instance_exec &block if block_given?
       end
 
-      def build(parent_path: '', meta: {}, callbacks: [])
-        # 合并 meta 时不仅仅是覆盖，比如 parameters 参数需要合并
-        meta2 = (meta || {}).merge(@meta_builder.build)
-        if meta[:parameters] && meta2[:parameters]
-          meta2[:parameters] = meta[:parameters].merge(meta2[:parameters])
-        end
-
-        # 构建子模块
-        # 合并父级传递过来的 callbacks，将 before 和 around 放在前面，after 放在后面
-        parent_before = callbacks.filter { |cb| cb[:lifecycle] == :before || cb[:lifecycle] == :around }
-        parent_after = callbacks.filter { |cb| cb[:lifecycle] == :after }
-        callbacks = parent_before + @callbacks + parent_after
-        mods = @mod_builders.map { |builder| builder.build(parent_path: Utils::Path.join(parent_path, @mod_prefix), meta: meta2, callbacks: callbacks) }
+      # meta 和 callbacks 是父级传递过来的，需要合并到当前模块或子模块中。
+      #
+      # 为什么一定要动态传递 meta_options 参数？由于 OpenAPI 文档是面向路由的，parameters、request_body、
+      # responses 都存在于路由文档中，对应地 Metadata 对象最终只存在于路由文档中。因此，在构建过程中，需要将父
+      # 级传递过来的 Metadata 对象合并到当前模块，再层层合并到子模块。
+      def build(meta_options: {}, callbacks: [])
+        meta_options = Utils::RouteDSLBuilders.merge_meta_options(meta_options, @meta_builder.build)
+        callbacks = Utils::RouteDSLBuilders.merge_callbacks(callbacks, @callbacks)
+        mods = @mod_builders.map { |builder| builder.build(meta_options: meta_options, callbacks: callbacks) }
 
         Application.new(
-          prefix: @mod_prefix,
+          prefix: @full_prefix,
           mods: mods,
           shared_mods: @shared_mods,
           error_guards: @error_guards
@@ -48,7 +45,7 @@ module Meta
 
       # 定义路由块
       def route(path, method = nil, &block)
-        route_builder = RouteDSL::RouteBuilder.new(path, method, &block)
+        route_builder = RouteBuilder.new(path, method, parent_path: @full_prefix, &block)
         @mod_builders << route_builder
         route_builder
       end
@@ -108,13 +105,9 @@ module Meta
           @meta = meta
         end
 
-        def build(parent_path: '', meta: {}, **kwargs)
-          # 合并 meta 时不仅仅是覆盖，比如 parameters 参数需要合并
-          meta2 = (meta || {}).merge(@meta)
-          if meta[:parameters] && meta2[:parameters]
-            meta2[:parameters] = meta[:parameters].merge(meta2[:parameters])
-          end
-          @builder.build(parent_path: parent_path, meta: meta2, **kwargs)
+        def build(meta_options: {}, **kwargs)
+          meta_options = Utils::RouteDSLBuilders.merge_meta_options(meta_options, @meta)
+          @builder.build(meta_options: meta_options, **kwargs)
         end
       end
     end

data/lib/meta/route_dsl/around_action_builder.rb

@@ -45,35 +45,45 @@ module Meta
         end
       end
 
-      # 使用 before、after、around 系列和当前 action 共同构建洋葱圈模型。
-      # Note: 该方法可能被废弃!
-      #
-      # 构建成功后，执行顺序是：
-      #
-      # - before 序列
-      # - around 序列的前半部分
-      # - action
-      # - around 序列的后半部分
-      # - after 序列
-      #
-      def self.build(before: [], after: [], around: [], action: nil)
-        builder = AroundActionBuilder.new
+      class << self
+        # 使用 before、after、around 系列和当前 action 共同构建洋葱圈模型。
+        # Note: 该方法已被废弃!
+        #
+        # 构建成功后，执行顺序是：
+        #
+        # - before 序列
+        # - around 序列的前半部分
+        # - action
+        # - around 序列的后半部分
+        # - after 序列
+        #
+        def build(before: [], after: [], around: [], action: nil)
+          builder = AroundActionBuilder.new
 
-        # 首先构建 before 序列，保证它最先执行
-        builder.around do |next_action|
-          before.each { |p| self.instance_exec(&p) }
-          next_action.execute(self)
-        end unless before.empty?
-        # 然后构建 after 序列，保证它最后执行
-        builder.around do |next_action|
-          next_action.execute(self)
-          after.each { |p| self.instance_exec(&p) }
-        end unless after.empty?
-        # 接着应用洋葱圈模型，依次构建 around 序列、action
-        around.each { |p| builder.around(&p) }
-        builder.around { self.instance_exec(&action) } unless action.nil?
+          # 首先构建 before 序列，保证它最先执行
+          builder.around do |next_action|
+            before.each { |p| self.instance_exec(&p) }
+            next_action.execute(self)
+          end unless before.empty?
+          # 然后构建 after 序列，保证它最后执行
+          builder.around do |next_action|
+            next_action.execute(self)
+            after.each { |p| self.instance_exec(&p) }
+          end unless after.empty?
+          # 接着应用洋葱圈模型，依次构建 around 序列、action
+          around.each { |p| builder.around(&p) }
+          builder.around { self.instance_exec(&action) } unless action.nil?
 
-        builder.build
+          builder.build
+        end
+
+        def build_from_callbacks(callbacks: [])
+          around_action_builder = AroundActionBuilder.new
+          callbacks.each do |cb|
+            around_action_builder.send(cb[:lifecycle], &cb[:proc]) if cb[:proc]
+          end
+          around_action_builder.build
+        end
       end
     end
   end