meta-api 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55ec631feb0038911007c4b1de6ca26fdf595ea84c41eecac046e417ff90a2e2
-  data.tar.gz: e384752c6ce459cb38adb4123078f10ad835c8f75a73256fddb1af02a8bac3b0
+  metadata.gz: 176e67a6d2a121ef7841ec614a2104f7f5f201c863ea88eb805e450b9ab13ee4
+  data.tar.gz: bd9be253deb822db45e2bf1c0548467652155dbf39255d49709da7b7d5a56726
 SHA512:
-  metadata.gz: 19c21dc3c99bebf4adfaea519ffb44d901481c8b88349b1b87677e3155a1c5e75e4c1e639596f589a28c32192e3ed10330f7d3b85dbc4e7238af73b0d8c996ef
-  data.tar.gz: 3903b5879a3d4dc1092a32b41aa17891434363089a48225acef22267ad6a56416ba7576c6de6ebb4bb8bbb50ebe2bebc7cb5592cf3265bccafe0e3c98e3c670c
+  metadata.gz: 2d1e5c80f3699d00bd529b74da7881eb559c089ab0bbb088560599453eea2972dc38dd082d991fc0be5e2815509987e8a3176d4d3fb0b041d35ae4ec5682c665
+  data.tar.gz: 59fcbd0be04d0d94a768f5b63e46a5ffcbc3a0a67ed89959ff957f8be4d1f9b7d04551cc090f6cc3a031effe45cebcb369d4a10f31fbc7a5811e2760a7f0b335

data/lib/meta/api.rb

@@ -1,5 +1,6 @@
 require_relative 'config'
 require_relative 'application'
+require_relative 'entity'
 require_relative 'swagger_doc'
 require_relative 'scope/base'
 require_relative 'load_i18n'

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

@@ -7,37 +7,38 @@ module Meta
     class ObjectSchemaBuilder
       extend Forwardable
 
-      module LockedMethodAlias
-        # 我在这里说明一下 lock_scope 的逻辑。
-        # 1. lock_scope 实际上是将 scope 传递到当前的 ObjectSchema 和它的子 Schema 中。
-        # 2. lock_scope 会叠加，也就是如果子 schema 也有 lock_scope，那么子 Schema 会将两个 Schema 合并起来。
-        # 3. 调用 filter(scope:) 和 to_schema_doc(scope:) 时，可以传递 scope 参数，这个 scope 遇到 lock_scope 时会合并。
-        # 4. 这也就是说，在路由级别定义的 scope 宏会传递到下面的 Schema 中去。
-        def add_scope(scope)
-          lock_scope(scope)
-        end
+      class Locked
+        # 定义一些 locked 的别名方法
+        module LockedMethodAlias
+          # 我在这里说明一下 lock_scope 的逻辑。
+          # 1. lock_scope 实际上是将 scope 传递到当前的 ObjectSchema 和它的子 Schema 中。
+          # 2. lock_scope 会叠加，也就是如果子 schema 也有 lock_scope，那么子 Schema 会将两个 Schema 合并起来。
+          # 3. 调用 filter(scope:) 和 to_schema_doc(scope:) 时，可以传递 scope 参数，这个 scope 遇到 lock_scope 时会合并。
+          # 4. 这也就是说，在路由级别定义的 scope 宏会传递到下面的 Schema 中去。
+          def add_scope(scope)
+            lock_scope(scope)
+          end
 
-        def lock(key, value)
-          locked(key => value)
-        end
+          def lock(key, value)
+            locked(key => value)
+          end
 
-        def method_missing(method, *args)
-          if method =~ /^lock_(\w+)$/
-            key = Regexp.last_match(1)
-            lock(key.to_sym, *args)
-          else
-            super
+          def method_missing(method, *args)
+            if method =~ /^lock_(\w+)$/
+              key = Regexp.last_match(1)
+              lock(key.to_sym, *args)
+            else
+              super
+            end
           end
         end
-      end
 
-      class Locked
         attr_reader :object_schema_builder, :locked_options
 
         # locked_options 是用户传递的参数，这个参数会被合并到 object_schema_builder 的 locked_options 中。
-        def initialize(builder, scope: nil, discard_missing: nil, exclude: nil)
+        def initialize(builder, **locked_options)
           @object_schema_builder = builder
-          @locked_options = ObjectSchema::USER_OPTIONS_CHECKER.check({ scope: scope, discard_missing: discard_missing, exclude: exclude }.compact)
+          @locked_options = SchemaOptions::UserOptions::Filter.check(locked_options.compact)
         end
 
         def to_schema
@@ -45,7 +46,7 @@ module Meta
         end
 
         def locked(options)
-          options = ObjectSchema::USER_OPTIONS_CHECKER.check(options)
+          options = SchemaOptions::UserOptions::Filter.check(options)
           options = ObjectSchema.merge_user_options(locked_options, options)
           Locked.new(self.object_schema_builder, **options)
         end
@@ -89,6 +90,8 @@ module Meta
       def initialize(options = {}, &)
         raise 'type 选项必须是 object' if !options[:type].nil? && options[:type] != 'object'
 
+        @schema_cache = {} # 用于缓存已经生成的 schema，重复利用
+
         @properties = {} # 所有的属性已经生成
         @required = []
         @validations = {}
@@ -98,7 +101,13 @@ module Meta
         @options = options
 
         properties&.each do |name, property_options|
-          property name, property_options
+          if property_options.is_a?(Hash)
+            property name, property_options
+          elsif property_options.is_a?(BaseSchema)
+            @properties[name.to_sym] = property_options
+          else
+            raise ArgumentError, "属性 #{name} 的类型不正确"
+          end
         end
 
         instance_exec(&) if block_given?
@@ -115,6 +124,7 @@ module Meta
 
       def property(name, options = {}, &block)
         @properties[name.to_sym] = Properties.build_property(options, ->(options) { SchemaBuilderTool.build(options, &block) })
+        # @properties[name.to_sym] = SchemaBuilderTool.build(options, &block)
       end
 
       alias expose property
@@ -139,7 +149,7 @@ module Meta
       end
 
       def render(options = {}, &block)
-        with_common_options(**options, params: false, &block)
+        with_common_options(**options, param: false, &block)
       end
 
       def merge(schema_builder)
@@ -148,41 +158,33 @@ module Meta
         @properties.merge!(schema_builder.properties)
       end
 
-      def to_schema(locked_options = nil)
+      def within(*properties)
+        to_schema.properties.within(*properties)
+      end
+      alias_method :[], :within
+
+      def to_schema(locked_options = {})
+        locked_options = SchemaOptions::UserOptions::Filter.check(locked_options.compact)
+        return @schema_cache[locked_options] if @schema_cache[locked_options]
+
         properties = @schema_name ? NamedProperties.new(@properties, @schema_name) : Properties.new(@properties)
-        ObjectSchema.new(properties: properties, options: @options, locked_options: locked_options)
+        @schema_cache[locked_options] = ObjectSchema.new(properties: properties, options: @options, locked_options: locked_options)
       end
 
       def locked(options)
-        # defined_scopes_mapping = {}
-        # # TODO: 将 properties 搞成 Properties 可以吗？
-        # defined_scopes = properties.map do |key, property|
-        #   property.defined_scopes(stage: :param, defined_scopes_mapping: defined_scopes_mapping)
-        # end.flatten.uniq
-        #
-        # user_scopes = options[:scope] || []
-        # user_scopes = [user_scopes] unless user_scopes.is_a?(Array)
-        #
-        # # 判断 user_scopes 中提供的局部 scope 是否在 defined_scopes 中
-        # local_user_scopes = user_scopes.reject { |scope| scope.start_with?('$') }
-        # if (local_user_scopes - defined_scopes).any?
-        #   extra_scopes = local_user_scopes - defined_scopes
-        #   raise ArgumentError, "scope #{extra_scopes.join(',')} 未在实体中定义"
-        # end
-
         Locked.new(self, **options)
       end
-      include LockedMethodAlias
+      include Locked::LockedMethodAlias
 
       private
 
-      def apply_array_scope?(options, block)
-        options[:type] == 'array' && (options[:items] || block)
-      end
+        def apply_array_scope?(options, block)
+          options[:type] == 'array' && (options[:items] || block)
+        end
 
-      def apply_object_scope?(options, block)
-        (options[:type] == 'object' || block) && (options[:properties] || block)
-      end
+        def apply_object_scope?(options, block)
+          (options[:type] == 'object' || block) && (options[:properties] || block)
+        end
     end
   end
 end

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

@@ -10,16 +10,16 @@ module Meta
   module JsonSchema
     class SchemaBuilderTool
       class << self
-        SCHEMA_BUILDER_OPTIONS = Utils::KeywordArgs::Builder.build do
-          permit_extras true
-
-          key :ref, alias_names: [:using], normalizer: ->(entity) { entity }
-          key :dynamic_ref, alias_names: [:dynamic_using], normalizer: ->(value) { value.is_a?(Proc) ? { resolve: value } : value }
-        end
         def build(options = {}, &block)
-          options = SCHEMA_BUILDER_OPTIONS.check(options)
+          options = SchemaOptions::BaseBuildOptions.check(options)
+          SchemaOptions.fix_type_option!(options)
 
-          if apply_array_schema?(options, block)
+          if apply_staging_schema?(options)
+            # 原则上，SchemaBuilderTool 不处理 param render scope 选项，这几个选项只会在 property 宏中出现，
+            # 并且交由 StagingSchema 和 ScopingSchema 专业处理。
+            # 只不过，经过后置修复后可能包含了 param 和 render 选项
+            StagingSchema.build_from_options(options)
+          elsif apply_array_schema?(options, block)
             ArraySchemaBuilder.new(options, &block).to_schema
           elsif apply_ref_schema?(options, block)
             RefSchemaBuilder.new(options).to_schema
@@ -34,21 +34,32 @@ module Meta
 
         private
 
-        def apply_array_schema?(options, block)
-          options[:type] == 'array'
-        end
+          def apply_staging_schema?(options)
+            if options.key?(:param)
+              return true if options[:param] == false || !options[:param].empty?
+            end
+            if options.key?(:render)
+              return true if options[:render] == false || !options[:render].empty?
+            end
+            false
+          end
 
-        def apply_object_schema?(options, block)
-          (options[:type] == 'object' || options[:type].nil?) && (options[:properties] || block)
-        end
+          def apply_array_schema?(options, block)
+            options[:type] == 'array'
+          end
 
-        def apply_ref_schema?(options, block)
-          options[:ref] != nil
-        end
+          def apply_object_schema?(options, block)
+            options[:properties] || block
+          end
+
+          def apply_ref_schema?(options, block)
+            options[:ref] != nil
+          end
+
+          def apply_dynamic_schema?(options, block)
+            options[:dynamic_ref] != nil
+          end
 
-        def apply_dynamic_schema?(options, block)
-          options[:dynamic_ref] != nil
-        end
       end
     end
   end

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

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require_relative '../../utils/kwargs/check'
 require_relative '../support/schema_options'
 
 module Meta
@@ -20,24 +19,6 @@ module Meta
     # 的地方都会抛出异常（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
-        key :enum, alias_names: [:allowable]
-        key :dynamic_ref, alias_names: [:dynamic_using], normalizer: ->(value) { value.is_a?(Proc) ? { resolve: value } : value }
-        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` 包含了转换器、验证器、文档、选项。
       #
       # 由于本对象可继承，基于不同的继承可分别表示基本类型、对象和数组，所以该属
@@ -49,10 +30,7 @@ module Meta
 
       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
+        @options = SchemaOptions::BaseBuildOptions.check(options)
       end
 
       def filter?
@@ -60,7 +38,7 @@ module Meta
       end
 
       def filter(value, user_options = {})
-        user_options = USER_OPTIONS_CHECKER.check(user_options)
+        user_options = SchemaOptions::UserOptions::Filter.check(user_options)
 
         value = value_callback(user_options) if options[:value]
         value = before_callback(value, user_options) if options[:before]

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

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require_relative '../../utils/kwargs/check'
 require_relative 'named_properties'
 
 module Meta
@@ -11,39 +10,6 @@ module Meta
       # scope:、discard_missing:、exclude: 等
       attr_reader :locked_options
 
-      normalize_scope = ->(value) {
-        raise ArgumentError, 'scope 选项不可传递 nil' if value.nil?
-        value = [value] unless value.is_a?(Array)
-        value.map do |v|
-          # 只要加入了 Meta::Scope::Base 模块，就有与 Meta::Scope 一样的行为
-          next v if v.is_a?(Meta::Scope::Base)
-
-          # 将 v 类名化
-          scope_name = v.to_s.split('_').map(&:capitalize).join
-          # 如果符号对应的类名不存在，就报错
-          if !defined?(::Scopes) || !::Scopes.const_defined?(scope_name)
-            raise NameError, "未找到常量 Scopes::#{scope_name}。如果你用的是命名 Scope（字符串或符号），则检查一下是不是拼写错误"
-          end
-          # 返回对应的常量
-          ::Scopes.const_get(scope_name)
-        end.compact
-      }
-      # stage 和 scope 选项在两个 CHECKER 下都用到了
-      USER_OPTIONS_CHECKER = Utils::KeywordArgs::Builder.build do
-        key :stage
-        key :scope, normalizer: normalize_scope
-        key :discard_missing, :exclude, :extra_properties, :type_conversion, :validation
-        key :execution, :user_data, :object_value
-      end
-      TO_SCHEMA_DOC_CHECKER = Utils::KeywordArgs::Builder.build do
-        key :stage
-        key :scope, normalizer: normalize_scope
-        key :schema_docs_mapping, :defined_scopes_mapping
-
-        # 以下是 filter 用到的选项，讲道理这些选项应该是不需要的，放置这些是为了防止报错
-        key :discard_missing
-      end
-
       def initialize(properties:, options: {}, locked_options: {})
         raise ArgumentError, 'properties 必须是 Properties 实例' unless properties.is_a?(Properties)
 
@@ -51,19 +17,20 @@ module Meta
 
         @properties = properties || Properties.new({}) # property 包含 stage，stage 包含 scope、schema
         @properties = Properties.new(@properties) if @properties.is_a?(Hash)
-        @locked_options = USER_OPTIONS_CHECKER.check(locked_options || {})
+        @locked_options = SchemaOptions::UserOptions::Filter.check(locked_options || {}, extras_handler: :ignore)
+        @locked_to_doc_options = SchemaOptions::UserOptions::ToDoc.check(locked_options || {}, extras_handler: :ignore)
       end
 
       def filter(object_value, user_options = {})
         # 合并 user_options
-        user_options = USER_OPTIONS_CHECKER.check(user_options)
+        user_options = SchemaOptions::UserOptions::Filter.check(user_options)
         user_options = self.class.merge_user_options(user_options, locked_options) if locked_options
         super
       end
 
       def to_schema_doc(user_options = {})
-        user_options = TO_SCHEMA_DOC_CHECKER.check(user_options)
-        user_options = self.class.merge_user_options(user_options, locked_options) if locked_options
+        user_options = SchemaOptions::UserOptions::ToDoc.check(user_options)
+        user_options = self.class.merge_user_options(user_options, @locked_to_doc_options) if @locked_to_doc_options
 
         schema = { type: 'object' }
         schema[:description] = options[:description] if options[:description]

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

@@ -94,6 +94,10 @@ module Meta
         self.class.new(@properties.merge(properties.instance_eval { @properties }))
       end
 
+      def within(*properties)
+        self.class.new(@properties.slice(*properties))
+      end
+
       def self.build_property(*args)
         StagingSchema.build_from_options(*args)
       end

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

@@ -54,13 +54,6 @@ module Meta
         defined_scopes_mapping[schema_name] = defined_scopes
         defined_scopes
       end
-
-      private
-
-      # # TODO: 这种带有组合方式的 Schema，让我联想到，每次 BaseSchema 新增一个方法都要在子 Schema 中加一遍，很烦！
-      # def defined_scopes
-      #   schema.defined_scopes
-      # end
     end
   end
 end

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

@@ -5,7 +5,6 @@ require_relative '../../scope/utils'
 
 module Meta
   module JsonSchema
-    # TODO: 作为模块引入
     class ScopingSchema < BaseSchema
       attr_reader :scope_matcher, :schema
 

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

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require_relative '../../utils/kwargs/check'
 require_relative '../support/schema_options'
 require_relative 'scoping_schema'
 require_relative 'unsupported_schema'
@@ -43,6 +42,10 @@ module Meta
         staged(stage).defined_scopes(stage: stage, **kwargs)
       end
 
+      def to_schema_doc(stage:, **kwargs)
+        staged(stage).to_schema_doc(stage: stage, **kwargs)
+      end
+
       def self.build_from_options(options, build_schema = ->(opts) { BaseSchema.new(opts) })
         param_opts, render_opts, common_opts = SchemaOptions.divide_to_param_and_render(options)
         if param_opts == common_opts && render_opts == common_opts

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

@@ -5,12 +5,64 @@ require_relative '../../utils/kwargs/builder'
 module Meta
   module JsonSchema
     module SchemaOptions
-      @default_options = {
-        scope: [],
-        required: false
-      }
+      BaseBuildOptions = Utils::Kwargs::Builder.build do
+        key :type, :items, :description, :presenter, :value, :default, :properties, :convert
+        key :validate, :required, :format
+        key :enum, alias_names: [:allowable]
+        key :ref, alias_names: [:using], normalizer: ->(entity) { entity }
+        key :dynamic_ref, alias_names: [:dynamic_using], normalizer: ->(value) { value.is_a?(Proc) ? { resolve: value } : value }
+        key :before, :after
+        key :if
+      end
+
+      module UserOptions
+        Common = Utils::Kwargs::Builder.build do
+          key :stage
+          key :scope, normalizer: ->(value) {
+            raise ArgumentError, 'scope 选项不可传递 nil' if value.nil?
+            value = [value] unless value.is_a?(Array)
+            value.map do |v|
+              # 只要加入了 Meta::Scope::Base 模块，就有与 Meta::Scope 一样的行为
+              next v if v.is_a?(Meta::Scope::Base)
+
+              # 将 v 类名化
+              scope_name = v.to_s.split('_').map(&:capitalize).join
+              # 如果符号对应的类名不存在，就报错
+              if !defined?(::Scopes) || !::Scopes.const_defined?(scope_name)
+                raise NameError, "未找到常量 Scopes::#{scope_name}。如果你用的是命名 Scope（字符串或符号），则检查一下是不是拼写错误"
+              end
+              # 返回对应的常量
+              ::Scopes.const_get(scope_name)
+            end.compact
+          }
+
+          handle_extras :merged
+        end
+        ToDoc = Utils::Kwargs::Builder.build(Common) do
+          key :schema_docs_mapping, :defined_scopes_mapping
+        end
+        Filter = Utils::Kwargs::Builder.build(Common) do
+          key :discard_missing, :exclude, :extra_properties, :type_conversion, :validation
+          key :execution, :user_data, :object_value
+        end
+      end
 
       class << self
+        def fix_type_option!(options)
+          if options[:type].is_a?(Class)
+            # 修复 type 为自定义类的情形
+            the_class = options[:type]
+            # 修复 param 选项
+            options[:param] = {} if options[:param].nil?
+            make_after_cast_to_class(options[:param], the_class) if options[:param]
+            # 修复 render 选项
+            options[:render] = {} if options[:render].nil?
+            make_before_match_to_class(options[:render], the_class) if options[:render]
+            # 最终确保 type 为 object
+            options.merge!(type: 'object')
+          end
+        end
+
         def divide_to_param_and_render(options)
           common_opts = (options || {}).dup
           param_opts = common_opts.delete(:param)
@@ -21,20 +73,6 @@ module Meta
           [param_opts, render_opts, common_opts]
         end
 
-        def normalize(options)
-          # 只要 options 中设置为 nil 的选项没有明确的意义，则下行代码是永远有效的
-          options = (@default_options.compact).merge(options.compact)
-          if options[:using]
-            if options[:type].nil?
-              options[:type] = 'object'
-            elsif options[:type] != 'object' && options[:type] != 'array'
-              raise "当使用 using 时，type 必须声明为 object 或 array"
-            end
-          end
-
-          options
-        end
-
         private
 
         def merge_common_to_stage(common_opts, stage_opts)
@@ -42,6 +80,37 @@ module Meta
           stage_opts = common_opts.merge(stage_opts) if stage_opts
           stage_opts
         end
+
+        def make_after_cast_to_class(options, the_class)
+          if options[:after].nil?
+            options[:after] = ->(value) { the_class.new(value) }
+          else
+            # 如果用户自定义了 after，那么我们需要在 after 之后再包一层
+            original_after_block = options[:after]
+            options[:after] = ->(value) do
+              value = instance_exec(value, &original_after_block)
+              the_class.new(value)
+            end
+          end
+        end
+
+        def make_before_match_to_class(options, the_class)
+          match_class = ->(value) do
+            raise ValidationError, "value 必须是 #{the_class} 类型" unless value.is_a?(the_class)
+            value
+          end
+          if options[:before].nil?
+            options[:before] = match_class
+          else
+            # 如果用户自定义了 before，那么我们需要在 before 之前再包一层
+            original_before_block = options[:before]
+            options[:before] = ->(value) do
+              value = match_class.call(value)
+              instance_exec(value, &original_before_block)
+            end
+          end
+        end
+
       end
     end
   end

data/lib/meta/route_dsl/parameters_builder.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative '../application/parameters'
-require_relative '../utils/kwargs/checker'
+require_relative '../utils/kwargs/helpers'
 
 module Meta
   module RouteDSL
@@ -18,9 +18,9 @@ module Meta
         # 修正 path 参数的选项
         options = options.dup
         if path_param_names.include?(name) # path 参数
-          options = Utils::KeywordArgs::Checker.fix!(options, in: 'path', required: true)
+          options = Utils::Kwargs::Helpers.fix!(options, in: 'path', required: true)
         else
-          options = Utils::KeywordArgs::Checker.merge_defaults!(options, in: 'query')
+          options = Utils::Kwargs::Helpers.merge_defaults!(options, in: 'query')
         end
 
         in_op = options.delete(:in)

data/lib/meta/route_dsl/route_builder.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'json'
-require_relative '../entity' # TODO: 放在这里不太合适
 require_relative '../application/route'
 require_relative 'chain_builder'
 require_relative 'action_builder'

data/lib/meta/route_dsl/uniformed_params_builder.rb

@@ -16,11 +16,11 @@ module Meta
       def param(name, options = {}, &block)
         options = (options || {}).dup
           if path_param_names.include?(name)
-            options = Utils::KeywordArgs::Checker.fix!(options, in: 'path', required: true)
+            options = Utils::Kwargs::Helpers.fix!(options, in: 'path', required: true)
           elsif @route_method == :get
-            options = Utils::KeywordArgs::Checker.merge_defaults!(options, in: 'query')
+            options = Utils::Kwargs::Helpers.merge_defaults!(options, in: 'query')
           else
-            options = Utils::KeywordArgs::Checker.merge_defaults!(options, in: 'body')
+            options = Utils::Kwargs::Helpers.merge_defaults!(options, in: 'body')
           end
 
         if options[:in] == 'body'

data/lib/meta/utils/kwargs/builder.rb

@@ -17,101 +17,44 @@
 #       key :a, :b, :c
 #       key :d, normalizer: ->(value) { normalize_to_array(value) }
 #     end
-#
+
+require_relative 'consumers'
+require_relative 'extras_consumers'
+require_relative 'checker'
 
 module Meta
   module Utils
-    class KeywordArgs
-      def initialize(arguments, permit_extras = false, final_consumer = nil)
-        @arguments = arguments
-        @permit_extras = permit_extras
-        @final_consumer = final_consumer
-      end
-
-      def check(args)
-        args = args.dup
-        final_args = {}
-
-        @arguments.each do |argument|
-          argument.consume(final_args, args)
-        end
-
-        # 做最终的修饰
-        @final_consumer.call(final_args, args) if @final_consumer
-
-        # 处理剩余字段
-        unless args.keys.empty?
-          if @permit_extras
-            final_args.merge!(args)
-          else
-            extras = args.keys
-            raise ArgumentError, "不接受额外的关键字参数：#{extras.join(', ')}" unless extras.empty?
-          end
-        end
-
-        final_args
-      end
-
-      class Argument
-        DEFAULT_TRANSFORMER = ->(value) { value }
-
-        def initialize(name:, normalizer: DEFAULT_TRANSFORMER, validator: nil, default: nil, alias_names: [])
-          @key_name = name
-          @consumer_names = [name] + alias_names
-          @default_value = default
-          @normalizer = normalizer
-          @validator = validator
-        end
-
-        def consume(final_args, args)
-          @consumer_names.each do |name|
-            return if consume_name(final_args, args, name)
-          end
-
-          final_args[@key_name] = @default_value unless @default_value.nil?
-        end
-
-        def consume_name(final_args, args, consumer_name)
-          if args.key?(consumer_name)
-            value = @normalizer.call(args.delete(consumer_name))
-            @validator.call(value) if @validator
-            final_args[@key_name] = value
-            true
-          else
-            false
-          end
-        end
-      end
-
+    class Kwargs
       class Builder
         def initialize
           @arguments = []
-          @permit_extras = false
-          @final_consumer = nil
+          @handle_extras = ExtrasConsumers::RaiseError
         end
 
         def key(*names, **options)
           names.each do |name|
-            @arguments << Argument.new(name: name, **options)
+            @arguments << ArgumentConsumer.new(name: name, **options)
           end
         end
 
-        def permit_extras(value)
-          @permit_extras = value
+        def handle_extras(sym)
+          @handle_extras = ExtrasConsumers.resolve_handle_extras(sym)
         end
 
-        def final_consumer(&block)
-          @final_consumer = block
+        def after_handler(&blk)
+          @after_handler = blk
         end
 
-        def build
-          KeywordArgs.new(@arguments, @permit_extras, @final_consumer)
+        def build(base_consumer = nil)
+          consumers = [base_consumer, *@arguments].compact
+          consumers = CompositeConsumer.new(*consumers)
+          Checker.new(arguments_consumer: consumers, extras_consumer: @handle_extras, after_handler: @after_handler)
         end
 
-        def self.build(&block)
+        def self.build(base_checker = nil, &block)
           builder = Builder.new
           builder.instance_exec &block
-          builder.build
+          builder.build(base_checker&.arguments_consumer)
         end
       end
     end

data/lib/meta/utils/kwargs/checker.rb

@@ -2,33 +2,34 @@
 
 module Meta
   module Utils
-    class KeywordArgs
-      module Checker
-        class << self
-          # 将 options 内的值修正为固定值，该方法会原地修改 options 选项。
-          # 如果 options 中的缺失相应的值，则使用 fixed_values 中的值补充；如果 options 中的值不等于 fixed_values 中对应的值，则抛出异常。
-          # 示例：
-          # （1）fix!({}, { a: 1, b: 2 }) # => { a: 1, b: 2 }
-          # （2）fix!({ a: 1 }, { a: 2 }) # raise error
-          def fix!(options, fixed_values)
-            fixed_values.each do |key, value|
-              if options.include?(key)
-                if options[key] != value
-                  raise ArgumentError, "关键字参数 #{key} 的值不正确，必须为 #{value}"
-                end
-              else
-                options[key] = value
-              end
-            end
-            options
-          end
+    class Kwargs
+      class Checker
+        attr_reader :arguments_consumer
 
-          def merge_defaults!(options, defaults)
-            defaults.each do |key, value|
-              options[key] = value unless options[key]
-            end
-            options
-          end
+        def initialize(arguments_consumer:, extras_consumer: nil, after_handler: nil)
+          @arguments_consumer = arguments_consumer
+          @extras_consumer = extras_consumer || ExtrasConsumers::RaiseError
+          @after_handler = after_handler
+        end
+
+        def check(args, extras_handler: nil)
+          # 准备工作
+          args = args.dup
+          final_args = {}
+
+          # 逐个消费参数
+          @arguments_consumer.consume(final_args, args)
+
+          # 处理额外参数
+          extras_consumer = ExtrasConsumers.resolve_handle_extras(extras_handler)
+          extras_consumer ||= @extras_consumer
+          extras_consumer&.consume(final_args, args)
+
+          # 后置处理器
+          @after_handler&.call(final_args)
+
+          # 返回最终参数
+          final_args
         end
       end
     end

data/lib/meta/utils/kwargs/consumers.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Meta
+  module Utils
+    class Kwargs
+      class ArgumentConsumer
+        DEFAULT_TRANSFORMER = ->(value) { value }
+
+        def initialize(name:, normalizer: DEFAULT_TRANSFORMER, validator: nil, default: nil, alias_names: [])
+          @key_name = name
+          @consumer_names = [name] + alias_names
+          @default_proc = -> { default.dup } if default
+          @normalizer = normalizer
+          @validator = validator
+        end
+
+        def consume(final_args, args)
+          @consumer_names.each do |name|
+            return if consume_name(final_args, args, name)
+          end
+
+          if @default_proc
+            default_value = @default_proc.call
+            final_args[@key_name] = @normalizer.call(default_value)
+          end
+        end
+
+        def consume_name(final_args, args, consumer_name)
+          if args.key?(consumer_name)
+            value = @normalizer.call(args.delete(consumer_name))
+            @validator.call(value) if @validator
+            final_args[@key_name] = value
+            true
+          else
+            false
+          end
+        end
+      end
+
+      class ProcConsumer
+        def initialize(&blk)
+          @block = blk
+        end
+
+        def consume(final_args, args)
+          @block.call(final_args, args) if @block
+        end
+      end
+
+      class CompositeConsumer
+        def initialize(*consumers)
+          @consumers = consumers
+        end
+
+        def consume(final_args, args)
+          @consumers.each do |consumer|
+            consumer.consume(final_args, args)
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/meta/utils/kwargs/extras_consumers.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Meta
+  module Utils
+    class Kwargs
+      module ExtrasConsumers
+        Ignore = ProcConsumer.new
+        Merged = ProcConsumer.new do |final_args, args|
+          final_args.merge!(args)
+        end
+        RaiseError = ProcConsumer.new do |final_args, args|
+          extras_keys = args.keys
+          raise ArgumentError, "不接受额外的关键字参数：#{extras_keys.join(', ')}" unless extras_keys.empty?
+        end
+
+        def self.resolve_handle_extras(sym)
+          return nil if sym.nil?
+
+          case sym
+          when :ignore
+            ExtrasConsumers::Ignore
+          when :merged
+            ExtrasConsumers::Merged
+          when :raise_error
+            ExtrasConsumers::RaiseError
+          else
+            raise ArgumentError, "handle_extras 只接受 :ignore, :merged, :raise_error 三种值，当前传递：#{sym}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/meta/utils/kwargs/helpers.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Meta
+  module Utils
+    class Kwargs
+      module Helpers
+        class << self
+          # 将 options 内的值修正为固定值，该方法会原地修改 options 选项。
+          # 如果 options 中的缺失相应的值，则使用 fixed_values 中的值补充；如果 options 中的值不等于 fixed_values 中对应的值，则抛出异常。
+          # 示例：
+          # （1）fix!({}, { a: 1, b: 2 }) # => { a: 1, b: 2 }
+          # （2）fix!({ a: 1 }, { a: 2 }) # raise error
+          def fix!(options, fixed_values)
+            fixed_values.each do |key, value|
+              if options.include?(key)
+                if options[key] != value
+                  raise ArgumentError, "关键字参数 #{key} 的值不正确，必须为 #{value}"
+                end
+              else
+                options[key] = value
+              end
+            end
+            options
+          end
+
+          def merge_defaults!(options, defaults)
+            defaults.each do |key, value|
+              options[key] = value unless options[key]
+            end
+            options
+          end
+        end
+      end
+    end
+  end
+end

data/meta-api.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name          = "meta-api"
-  spec.version       = "0.1.2"
+  spec.version       = "0.2.0"
   spec.authors       = ["yetrun"]
   spec.email         = ["yetrun@foxmail.com"]
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: meta-api
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - yetrun
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-05 00:00:00.000000000 Z
+date: 2024-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hash_to_struct
@@ -85,8 +85,10 @@ files:
 - lib//meta/scope/utils.rb
 - lib//meta/swagger_doc.rb
 - lib//meta/utils/kwargs/builder.rb
-- lib//meta/utils/kwargs/check.rb
 - lib//meta/utils/kwargs/checker.rb
+- lib//meta/utils/kwargs/consumers.rb
+- lib//meta/utils/kwargs/extras_consumers.rb
+- lib//meta/utils/kwargs/helpers.rb
 - lib//meta/utils/path.rb
 - lib//meta/utils/route_dsl_builders.rb
 - meta-api.gemspec

data/lib/meta/utils/kwargs/check.rb

@@ -1,91 +0,0 @@
-# frozen_string_literal: true
-
-# 运行时检查关键字参数。（已过时，请使用 Builder）
-#
-# 在 Ruby 3 中，关键字参数有所变化。简单来说，关键字参数和 Hash 类型不再自动转化，并且一般情况下推荐使用关键字参数。
-# 但关键字参数还是有稍稍不足之处，比如在做一些复杂的关键字参数定义时。
-#
-# 这个文件编写了一个方法，帮助我们在运行时检查关键字参数。这样，我们就可以像下面这样笼统的方式定义参数，不必用明确的关
-# 键字参数名称。
-#
-#     def method_name(x, y, z, **kwargs); end
-#     def method_name(x, y, z, kwargs={}); end
-#
-# 使用示例：
-#
-#     # 返回 { x: 1, y: 2, z: 3 }
-#     Meta::Utils::KeywordArgs.check(args: { x: 1, y: 2 }, schema: [:x, :y, { z: 3 }])
-#
-#     # 返回 { x: 1, y: 2, z: 4 }
-#     Meta::Utils::KeywordArgs.check(args: { x: 1, y: 2, z: 4 }, schema: [:x, :y, { z: 3 }])
-#
-#     # Error: `x` is required
-#     Meta::Utils::KeywordArgs.check(args: { y: 2, z: 3 }, schema: [:x, :y, { z: 3 }])
-#
-#     # Error: `a` is not allowed
-#     Meta::Utils::KeywordArgs.check(args: { a: 1, y: 2, z: 3 }, schema: [:x, :y, { z: 3 }])
-
-module Meta
-  module Utils
-    class KeywordArgs
-      class << self
-        def check(args:, schema:)
-          schemas = build_schemas(schema)
-
-          # 不接受额外的关键字参数
-          extras = args.keys - schemas.keys
-          raise "不接受额外的关键字参数：#{extras.join(', ')}" unless extras.empty?
-
-          # 通过 schema 导出关键字参数
-          missing = []
-          result = schemas.map do |name, spec|
-            if args.include?(name)
-              [name, args[name]]
-            elsif spec.include?(:default)
-              [name, spec[:default]]
-            else
-              missing << name
-            end
-          end.to_h
-
-          # 检查以上导出过程中是否找到缺失的参数
-          if missing.empty?
-            result
-          else
-            raise "缺失必要的关键字参数：#{missing.join(', ')}"
-          end
-        end
-
-        private
-
-        def build_schemas(spec)
-          if spec.is_a?(Array)
-            build_schemas_from_array(spec)
-          elsif spec.is_a?(Hash)
-            build_schemas_from_hash(spec)
-          elsif spec.is_a?(Symbol)
-            build_schemas_from_symbol(spec)
-          else
-            raise "未知的参数类型：#{spec.class}"
-          end
-        end
-
-        def build_schemas_from_array(spec_array)
-          spec_array.inject({}) do |accumulated, val|
-            accumulated.merge!(build_schemas(val))
-          end
-        end
-
-        def build_schemas_from_hash(spec_hash)
-          spec_hash.transform_values do |val|
-            { default: val }
-          end
-        end
-
-        def build_schemas_from_symbol(spec_symbol)
-          { spec_symbol => {} }
-        end
-      end
-    end
-  end
-end