meta-api 0.1.1 → 0.2.0

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

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
 require_relative '../support/scope_matcher'
+require_relative '../../scope/utils'
 
 module Meta
   module JsonSchema
     class ScopingSchema < BaseSchema
       attr_reader :scope_matcher, :schema
 
-      def initialize(scope_matcher_options: , schema:)
-        @scope_matcher = ScopeMatcher.new(scope_matcher_options)
+      def initialize(scope_matcher:, schema:)
+        # raise ArgumentError, 'scope_matcher 不能是一个数组' if scope_matcher.is_a?(Array)
+
+        @scope_matcher = Scope::Utils.parse(scope_matcher)
         @schema = schema
       end
 
@@ -32,7 +35,7 @@ module Meta
         options = options.dup
         scope_matcher_options = options.delete(:scope)
         schema = build_schema.call(options)
-        schema = ScopingSchema.new(scope_matcher_options: scope_matcher_options, schema: schema) if scope_matcher_options
+        schema = ScopingSchema.new(scope_matcher: scope_matcher_options, schema: schema) if scope_matcher_options
         schema
       end
     end

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/json_schema/support/scope_matcher.rb

@@ -7,19 +7,22 @@ module Meta
 
       def initialize(query_clause)
         query_clause = [query_clause] if query_clause.is_a?(String) || query_clause.is_a?(Symbol)
-        query_clause = { some_of: query_clause } if query_clause.is_a?(Array)
+        query_clause = { all_of: query_clause } if query_clause.is_a?(Array)
 
         @match_type, @defined_scopes = query_clause.first
       end
 
-      def match?(scopes)
-        return false if scopes.empty?
+      def match?(providing_scopes)
+        # 目前认为空数组就是不做 scope 筛选
+        return false if providing_scopes.empty?
 
         case @match_type
         when :some_of
-          (@defined_scopes & scopes).any?
+          # 只要相交就可以
+          (@defined_scopes & providing_scopes).any?
         when :all_of
-          (@defined_scopes - scopes).empty?
+          # @defined_scopes 一定要被包含在 providing_scopes 内
+          (@defined_scopes - providing_scopes).empty?
         else
           raise "Unknown match type: #{@match_type}"
         end

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

@@ -26,9 +26,9 @@ module Meta
           next if value.nil?
           raise JsonSchema::ValidationError, I18n.t(:'json_schema.errors.format') unless value =~ format
         },
-        allowable: proc { |value, allowable_values|
+        enum: proc { |value, allowable_values|
           next if value.nil?
-          raise JsonSchema::ValidationError, I18n.t(:'json_schema.errors.allowable', allowable_values: allowable_values) unless allowable_values.include?(value)
+          raise JsonSchema::ValidationError, I18n.t(:'json_schema.errors.enum', allowable_values: allowable_values) unless allowable_values.include?(value)
         }
       }
 

data/lib/meta/route_dsl/meta_builder.rb

@@ -45,9 +45,6 @@ module Meta
 
       def scope(scope)
         scope = [scope] unless scope.is_a?(Array)
-        unless scope.all? { |s| s.start_with?('$') }
-          raise ArgumentError, 'namespace 和 route 中声明的 scope 必须是全局 scope（以 $ 开头）'
-        end
 
         @meta[:scope] = scope
       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,12 +18,13 @@ 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)
+        raise ArgumentError, "in 选项只能是 path, query, header, body" unless %w[path query header body].include?(in_op)
         @parameter_options[name] = { in: in_op, schema: JsonSchema::BaseSchema.new(options) }
       end
 

data/lib/meta/route_dsl/route_builder.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'json'
-require_relative '../entity'
 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/scope/base.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Meta
+  class Scope
+    module Errors
+      class NameNotSet < StandardError; end
+    end
+
+    # 基本的 Scope 方法，引入该模块即可获取系列方法
+    module Base
+      def match?(scopes)
+        scopes = [scopes] unless scopes.is_a?(Array)
+        match_scopes?(scopes)
+      end
+
+      def match_scopes?(scopes)
+        return true if @forwarded_scope&.match?(scopes)
+        scopes.include?(self)
+      end
+
+      def defined_scopes
+        [self]
+      end
+
+      def scope_name
+        scope_name = @scope_name || self.name
+        raise Errors::NameNotSet, '未设置 scope 名称' if scope_name.nil?
+
+        scope_name.split('::').last
+      end
+
+      def scope_name=(name)
+        @scope_name = name.to_s
+      end
+
+      def include_scope(*scopes)
+        @forwarded_scope = Composite.concat(@forwarded_scope, *scopes)
+      end
+
+      # 既作为类方法，也作为实例方法
+      def and(*scopes)
+        scopes = [self, *scopes] if self != Meta::Scope
+        And.new(*scopes)
+      end
+      alias_method :&, :and
+
+      # 既可以是类方法，也可以是实例方法
+      def or(*scopes)
+        scopes = [self, *scopes] if self != Meta::Scope
+        Or.new(*scopes)
+      end
+      alias_method :|, :or
+
+      def inspect
+        scope_name || super
+      end
+    end
+
+    # 将 Scope 类的子类作为 Scope 实例
+    class << self
+      include Base
+
+      def new(*args)
+        raise NoMethodError, 'Meta::Scope 类不能实例化'
+      end
+
+      def inherited(subclass)
+        # subclass.instance_variable_set(:@forwarded_scope, Or.new)
+
+        # 如果是 Meta::Scope 的具体子类被继承，该子类加入到 @included_scopes 原语中
+        subclass.include_scope(self) if self != Meta::Scope
+      end
+
+      def include(*mods)
+        scopes = mods.filter { |m| m < Meta::Scope }
+        mods = mods - scopes
+
+        include_scope(*scopes) if scopes.any?
+        super(*mods) if mods.any?
+      end
+    end
+
+    # 组合式 Scope 实例，用于表示多个 Scope 的逻辑操作
+    class Composite
+      include Base
+
+      def self.new(*scopes)
+        if scopes.length == 0
+          @empty || (@empty = self.new)
+        elsif scopes.length == 1
+          scopes[0]
+        else
+          super(*scopes)
+        end
+      end
+
+      def self.concat(*scopes)
+        composite_classes = scopes.filter { |scope| scope.is_a?(Composite) }
+                                  .map(&:class).uniq
+        raise ArgumentError, "不能执行 concat，参数中包含了多个逻辑运算符：#{composite_classes.join(',')}" if composite_classes.length > 1
+
+        if composite_classes.empty?
+          Or.new(*scopes)
+        else
+          composite_classes[0].new(*scopes)
+        end
+      end
+
+      def initialize(*scopes)
+        @scopes = scopes.compact.map do |scope|
+          scope.is_a?(self.class) ? scope.defined_scopes : scope
+        end.flatten.freeze
+      end
+
+      def defined_scopes
+        @scopes
+      end
+
+      def scope_name
+        @scope_name || @scopes.map(&:scope_name).sort.join('_')
+      end
+    end
+
+    # 逻辑 And 操作
+    class And < Composite
+      # scopes 需要包含所有的 @scopes
+      def match_scopes?(scopes)
+        @scopes.all? { |scope| scope.match?(scopes) }
+      end
+
+      # 重定义 scope_name，如果用得上的话
+      def scope_name
+        @scope_name || @scopes.map(&:scope_name).sort.join('_and_')
+      end
+    end
+
+    # 另一种 Scope 实例，用于表示多个 Scope 的逻辑 Or 操作
+    class Or < Composite
+      include Base
+
+      # scopes 只需要包含一个 @scopes
+      def match_scopes?(scopes)
+        @scopes.any? { |scope| scope.match?(scopes) }
+      end
+
+      # 重定义 scope_name，如果用得上的话
+      def scope_name
+        @scope_name || @scopes.map(&:scope_name).sort.join('_or_')
+      end
+    end
+  end
+end

data/lib/meta/scope/utils.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+# 兼容以前的字符串 scope
+module Meta
+  class Scope
+    module Utils
+      class << self
+        # 根据选项构建 Scope 实例，这是兼容之前的字符串写法。
+        def parse(scope)
+          scope = [scope] if scope.is_a?(String) || scope.is_a?(Symbol)
+
+          # 只会有两种类型：Array[String] 和 Scope 子类
+          if scope.is_a?(Meta::Scope::Base)
+            scope
+          elsif scope.is_a?(Array)
+            scopes = scope.map { |s| parse_string(s) }
+            Or.new(*scopes)
+          else
+            raise ArgumentError, 'scope 参数必须是一个数组或者 Scope 子类'
+          end
+        end
+
+        def and(*scopes)
+          scopes = scopes.map { |s| parse(s) }
+          And.new(*scopes)
+        end
+
+        private
+
+          def parse_string(str)
+            # 确保全局存在一个 Scopes 模块
+            unless defined?(::Scopes)
+              scopes = Module.new
+              Object.const_set(:Scopes, scopes)
+            end
+
+            # 获取类名化的 scope 名称
+            scope_name = str.to_s.split('_').map(&:capitalize).join
+
+            # 如果 Scopes 模块中已经存在该 scope 类，直接返回
+            return ::Scopes.const_get(scope_name) if ::Scopes.const_defined?(scope_name)
+
+            # 如果不存在，创建一个新的类
+            scope_class = Class.new(Meta::Scope)
+            scope_class.scope_name = str
+            ::Scopes.const_set(scope_name, scope_class)
+
+            # 返回结果
+            scope_class
+          end
+      end
+    end
+  end
+end

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 "不接受额外的关键字参数：#{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