meta-api 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf3fb639df71a5353328e898711c9758c5e5fd3dd1760409ae823fbd0a7852e2
-  data.tar.gz: ea5dd728c3691fcf542d1085fd21d787d727c97b588652de3ffdd53b67512437
+  metadata.gz: 55ec631feb0038911007c4b1de6ca26fdf595ea84c41eecac046e417ff90a2e2
+  data.tar.gz: e384752c6ce459cb38adb4123078f10ad835c8f75a73256fddb1af02a8bac3b0
 SHA512:
-  metadata.gz: 4a9f0a02d8091f77e7f9c2ea0ea67b86f1877327a7b75a7f4342fecd7f2822f9bde2ded59c20cb1c3227eb88a4b6b098c9438710a6a8eedcf4c8defb2f37c572
-  data.tar.gz: 2e7911858914bd1b34ff60007f48757f6afb1183c59d15d9e490fb5fe781244522d5500251dcbdbb02fc5f26a17d48ab82bbc2f6dd4368c2540f97bb351f6da3
+  metadata.gz: 19c21dc3c99bebf4adfaea519ffb44d901481c8b88349b1b87677e3155a1c5e75e4c1e639596f589a28c32192e3ed10330f7d3b85dbc4e7238af73b0d8c996ef
+  data.tar.gz: 3903b5879a3d4dc1092a32b41aa17891434363089a48225acef22267ad6a56416ba7576c6de6ebb4bb8bbb50ebe2bebc7cb5592cf3265bccafe0e3c98e3c670c

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 更新日志
 
+## 0.1.2（2024 年 6 月 5 日）
+
+1. 实现新的基于常量的 Scope 场景化模式。
+2. 属性的 `scope:` 选项如果传递的是字符串数组，则恢复为 `或` 模式。
+3. 取消 HTTP method 自动生成对应的 Scope常量。
+4. 修复 `locked(discard_missing: true)` 时生成文档报错。
+5. 属性新增 `enum:` 选项，`allowable:` 作为其别名存在。
+
+## 0.1.1（2024 年 6 月 1 日）
+
+1. 添加 `Meta::Entity.with_common_options` 方法，用于更有效地组织字段。
+2. 临时性地添加 `Meta::Entity.merge` 方法，作为合并其他的实体的暂时性实现。
+3. scope 分为全局 scope 和局部 scope.
+
 ## 0.1.0（2023 年 8 月 5 日）
 
 1. 删除 `on:` 选项。

data/config/locales/zh-CN.yml

@@ -6,7 +6,7 @@ zh-CN:
     errors:
       required: "未提供"
       format: "格式不正确"
-      allowable: "不在允许的值范围内，允许的值包括 [%{allowable_values}]"
+      enum: "不在允许的值范围内，允许的值包括 [%{allowable_values}]"
       type_convert:
         basic: "类型转化失败，期望得到一个 `%{target_type}` 类型，但值 `%{value}` 无法转化"
         array: "转化为数组类型时期望对象拥有 `to_a` 方法"

data/lib/meta/api.rb

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

data/lib/meta/application/metadata.rb

@@ -13,23 +13,21 @@ module Meta
       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
+          **{ execution: execution, stage: :param, scope: @scope, 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,
+          **{ execution: execution, stage: :render, scope: @scope }.compact,
           **user_options,
         )
       end

data/lib/meta/application/route.rb

@@ -39,7 +39,8 @@ module Meta
     end
 
     def generate_operation_doc(schemas)
-      meta.generate_operation_doc(schemas, scope: ["$#{method}"])
+      # 不再自动添加 $post 等 scope
+      meta.generate_operation_doc(schemas, scope: [])
     end
   end
 end

data/lib/meta/entity.rb

@@ -14,43 +14,17 @@ module Meta
       def inherited(base)
         base.instance_eval do
           @schema_builder = JsonSchema::ObjectSchemaBuilder.new
-          @schema_builder.schema_name(self.name) if self.name
+          if self.name
+            mod_names = self.name.split("::")
+            mod_names.shift if mod_names.first == "Entities"
+            schema_name = mod_names.join('_')
+            @schema_builder.schema_name(schema_name)
+          end
         end
       end
 
-      def_delegators :schema_builder, :property, :param, :expose, :use, :lock, :locked, :schema_name, :to_schema
-
-      def method_missing(method, *args)
-        if method =~ /^lock_(\w+)$/
-          schema_builder.send(method, *args)
-        else
-          super
-        end
-      end
-
-      private
-
-      # TODO: 不需要在 Entity 内自动生成名称了，交给 ObjectSchema::Naming 去做吧
-      def generate_schema_name(stage, locked_scopes)
-        # 匿名类不考虑自动生成名称
-        return nil unless self.name
-
-        schema_name = self.name.gsub('::', '_')
-        schema_name = schema_name.delete_suffix('Entity') unless schema_name == 'Entity'
-
-        # 先考虑 stage
-        case stage
-        when :param
-          schema_name += 'Params'
-        when :render
-          schema_name += 'Entity'
-        end
-
-        # 再考虑 locked_scope
-        scope_suffix = locked_scopes.join('_')
-        schema_name = "#{schema_name}_#{scope_suffix}" unless scope_suffix.empty?
-
-        schema_name
+      def method_missing(method, *args, **kwargs, &)
+        schema_builder.send(method, *args, **kwargs, &)
       end
     end
   end

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

@@ -5,6 +5,8 @@ require_relative '../schemas/properties'
 module Meta
   module JsonSchema
     class ObjectSchemaBuilder
+      extend Forwardable
+
       module LockedMethodAlias
         # 我在这里说明一下 lock_scope 的逻辑。
         # 1. lock_scope 实际上是将 scope 传递到当前的 ObjectSchema 和它的子 Schema 中。
@@ -29,10 +31,65 @@ module Meta
         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)
+          @object_schema_builder = builder
+          @locked_options = ObjectSchema::USER_OPTIONS_CHECKER.check({ scope: scope, discard_missing: discard_missing, exclude: exclude }.compact)
+        end
+
+        def to_schema
+          object_schema_builder.to_schema(locked_options)
+        end
+
+        def locked(options)
+          options = ObjectSchema::USER_OPTIONS_CHECKER.check(options)
+          options = ObjectSchema.merge_user_options(locked_options, options)
+          Locked.new(self.object_schema_builder, **options)
+        end
+        include LockedMethodAlias
+      end
+
+      class WithCommonOptions
+        attr_reader :object_schema_builder, :common_options
+
+        def initialize(builder, common_options, &)
+          @object_schema_builder = builder
+          @common_options = common_options
+
+          instance_exec(&) if block_given?
+        end
+
+        def property(name, options = {}, &block)
+          options = merge_options(options)
+          object_schema_builder.property(name, options, &block)
+        end
+
+        def merge_options(options)
+          self.class.merge_options(common_options, options)
+        end
+
+        def self.merge_options(common_options, options)
+          common_options.merge(options) do |key, oldVal, newVal|
+            if key == :scope
+              # 合并 common_options 和 options 中的 scope 选项
+              Scope::Utils.and(oldVal, newVal)
+            else
+              # 关于 param、render 内部选项的合并问题暂不考虑
+              newVal
+            end
+          end
+        end
+      end
+
+      attr_reader :properties
+
       def initialize(options = {}, &)
         raise 'type 选项必须是 object' if !options[:type].nil? && options[:type] != 'object'
 
-        @properties = {}
+        @properties = {} # 所有的属性已经生成
         @required = []
         @validations = {}
 
@@ -47,10 +104,13 @@ module Meta
         instance_exec(&) if block_given?
       end
 
-      def schema_name(schema_base_name)
-        raise TypeError, "schema_base_name 必须是一个 String，当前是：#{schema_base_name.class}" unless schema_base_name.is_a?(String)
-
-        @schema_name = schema_base_name
+      def schema_name(schema_base_name = nil)
+        if schema_base_name
+          raise TypeError, "schema_base_name 必须是一个 String，当前是：#{schema_base_name.class}" unless schema_base_name.is_a?(String)
+          @schema_name = schema_base_name
+        else
+          @schema_name
+        end
       end
 
       def property(name, options = {}, &block)
@@ -66,12 +126,50 @@ module Meta
         instance_exec(&proc)
       end
 
+      def with_common_options(common_options, &block)
+        WithCommonOptions.new(self, common_options, &block)
+      end
+
+      def scope(scope, options = {}, &)
+        with_common_options(**options, scope: scope, &)
+      end
+
+      def params(options = {}, &block)
+        with_common_options(**options, render: false, &block)
+      end
+
+      def render(options = {}, &block)
+        with_common_options(**options, params: false, &block)
+      end
+
+      def merge(schema_builder)
+        schema_builder = schema_builder.schema_builder if schema_builder.respond_to?(:schema_builder)
+
+        @properties.merge!(schema_builder.properties)
+      end
+
       def to_schema(locked_options = nil)
         properties = @schema_name ? NamedProperties.new(@properties, @schema_name) : Properties.new(@properties)
         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
@@ -85,27 +183,6 @@ module Meta
       def apply_object_scope?(options, block)
         (options[:type] == 'object' || block) && (options[:properties] || block)
       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)
-          @object_schema_builder = builder
-          @locked_options = ObjectSchema::USER_OPTIONS_CHECKER.check({ scope: scope, discard_missing: discard_missing, exclude: exclude }.compact)
-        end
-
-        def to_schema
-          object_schema_builder.to_schema(locked_options)
-        end
-
-        def locked(options)
-          options = ObjectSchema::USER_OPTIONS_CHECKER.check(options)
-          options = ObjectSchema.merge_user_options(locked_options, options)
-          Locked.new(self.object_schema_builder, **options)
-        end
-        include LockedMethodAlias
-      end
     end
   end
-end
+end

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

@@ -13,9 +13,7 @@ module Meta
         SCHEMA_BUILDER_OPTIONS = Utils::KeywordArgs::Builder.build do
           permit_extras true
 
-          key :ref, alias_names: [:using], normalizer: ->(entity) {
-            entity
-          }
+          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)

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

@@ -22,7 +22,9 @@ module Meta
     class BaseSchema
       OPTIONS_CHECKER = Utils::KeywordArgs::Builder.build do
         key :type, :items, :description, :presenter, :value, :default, :properties, :convert
-        key :validate, :required, :format, :allowable
+        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
@@ -89,7 +91,7 @@ module Meta
       end
 
       # 返回能够处理 scope 和 stage 的 schema（可以是 self），否则应返回 UnsupportedStageSchema 或 nil.
-      def find_schema(scope:, stage:)
+      def find_schema(stage:, scope:)
         staged(stage)&.scoped(scope)
       end
 
@@ -103,19 +105,22 @@ module Meta
         self
       end
 
+      # defined_scopes_mapping 是一个 Hash，用于缓存已经计算出的 scopes，用于避免重复计算。其主要针对的是具有命名系统的 Schema，如 Meta::Entity
       def defined_scopes(stage:, defined_scopes_mapping:)
         []
       end
 
       # 执行 if: 选项，返回 true 或 false
-      def if?(user_options)
-        return true if options[:if].nil?
+      def if?(object_value, execution = nil)
+        if_block = options[:if]
+        return true if if_block.nil?
 
-        execution = user_options[:execution]
+        args_length = if_block.lambda? ? if_block.arity : 1
+        args = args_length > 0 ? [object_value] : []
         if execution
-          execution.instance_exec(&options[:if])
+          execution.instance_exec(*args, &options[:if])
         else
-          options[:if]&.call
+          options[:if]&.call(*args)
         end
       end
 
@@ -136,7 +141,7 @@ module Meta
         schema = {}
         schema[:type] = options[:type] if options[:type]
         schema[:description] = options[:description] if options[:description]
-        schema[:enum] = options[:allowable] if options[:allowable]
+        schema[:enum] = options[:enum] if options[:enum]
 
         schema
       end

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

@@ -11,25 +11,37 @@ 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: ->(value) {
-          raise ArgumentError, 'scope 选项不可传递 nil' if value.nil?
-          value = [value] unless value.is_a?(Array)
-          value
-        }
+        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: ->(value) {
-          raise ArgumentError, 'scope 选项不可传递 nil' if value.nil?
-          value = [value] unless value.is_a?(Array)
-          value
-        }
+        key :scope, normalizer: normalize_scope
         key :schema_docs_mapping, :defined_scopes_mapping
+
+        # 以下是 filter 用到的选项，讲道理这些选项应该是不需要的，放置这些是为了防止报错
+        key :discard_missing
       end
 
       def initialize(properties:, options: {}, locked_options: {})
@@ -42,17 +54,6 @@ module Meta
         @locked_options = USER_OPTIONS_CHECKER.check(locked_options || {})
       end
 
-      # 复制一个新的 ObjectSchema，只有 options 不同
-      def dup(options)
-        raise UnsupportedError, 'dup 不应该再执行了'
-
-        self.class.new(
-          properties: properties,
-          options: options,
-          locked_options: locked_options,
-        )
-      end
-
       def filter(object_value, user_options = {})
         # 合并 user_options
         user_options = USER_OPTIONS_CHECKER.check(user_options)
@@ -60,35 +61,59 @@ module Meta
         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
+
+        schema = { type: 'object' }
+        schema[:description] = options[:description] if options[:description]
+        properties, required_keys = @properties.to_swagger_doc(**user_options)
+        schema[:properties] = properties unless properties.empty?
+        schema[:required] = required_keys unless required_keys.empty?
+        schema
+      end
+
       def naming?
         properties.is_a?(NamedProperties)
       end
 
+      def defined_scopes(stage:, defined_scopes_mapping:)
+        properties.defined_scopes(stage: stage, defined_scopes_mapping: defined_scopes_mapping)
+      end
+
+      # 解析当前 Schema 的名称
+      #
+      # 名称解析的规则是：
+      # 1. 结合基础的 schema_name，如果它是参数，就加上 Params 后缀；如果它是返回值，就加上 Entity 后缀
+      # 2. 而后跟上 locked_scope. 这里，会把多余的 scope 去掉。比如，一个实体内部只处理 Admin 的 scope，但是外部传进来了
+      #    Admin 和 Detail，那么名称只会包括 Admin
       def resolve_name(stage, user_scopes, defined_scopes)
         raise ArgumentError, 'stage 不能为 nil' if stage.nil?
 
         # 先合成外面传进来的 scope
         locked_scopes = (locked_options || {})[:scope] || []
         user_scopes = (user_scopes + locked_scopes).uniq
-        scopes = user_scopes & defined_scopes
 
         # 再根据 stage 和 scope 生成为当前的 Schema 生成一个合适的名称，要求保证唯一性
-        schema_name = properties.schema_name(stage)
-        schema_name += "__#{scopes.join('__')}" unless scopes.empty?
-        schema_name
-      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
+        base_schema_name = properties.schema_name(stage)
 
-        schema = { type: 'object' }
-        schema[:description] = options[:description] if options[:description]
+        # 将调用转移到 Scopes 模块下
+        resolve_name_helper(base_schema_name, user_scopes, defined_scopes)
+      end
 
-        properties, required_keys = @properties.to_swagger_doc(**user_options)
-        schema[:properties] = properties unless properties.empty?
-        schema[:required] = required_keys unless required_keys.empty?
-        schema
+      # 帮助实体解析名称，这里主要是考虑 scope 的作用
+      #
+      # base_schema_name: 具有 Params 或 Entity 后缀的基础名称
+      # user_scopes: 用户传进来的 scope 数组
+      # candidate_scopes: 从实体中找出的能够参与命名的备选的 scope 数组
+      def resolve_name_helper(base_schema_name, user_scopes, candidate_scopes)
+        # 从备选的 scope 中获取到被利用到的
+        scopes = candidate_scopes.filter { |candidate_scope| candidate_scope.match?(user_scopes) }
+        scope_names = scopes.map(&:scope_name)
+
+        # 合成新的名字
+        schema_name_parts = [base_schema_name] + scope_names
+        schema_name_parts.join('__')
       end
 
       def locked_scope

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

@@ -30,7 +30,7 @@ module Meta
           next false if exclude && exclude.include?(name)
 
           # 通过 if 选项过滤
-          next false unless property_schema.if?(user_options)
+          next false unless property_schema.if?(object_value, user_options[:execution])
 
           # 默认返回 true
           next true
@@ -71,8 +71,7 @@ module Meta
 
       # user_options 包括 stage, scope, schema_docs_mapping, defined_scopes_mapping
       def to_swagger_doc(scope: [], stage: nil, **user_options)
-        locked_scopes = scope
-        properties = filter_by(stage: stage, user_scope: locked_scopes)
+        properties = filter_by(stage: stage, user_scope: scope)
         required_keys = properties.filter do |key, property_schema|
           property_schema.options[:required]
         end.keys
@@ -82,6 +81,12 @@ module Meta
         [properties, required_keys]
       end
 
+      def defined_scopes(stage:, defined_scopes_mapping:)
+        @properties.each_with_object([]) do |(name, property), defined_scopes|
+          defined_scopes.concat(property.defined_scopes(stage: stage, defined_scopes_mapping: defined_scopes_mapping))
+        end
+      end
+
       # 程序中有些地方用到了这三个方法
       def_delegators :@properties, :empty?, :key?, :[], :each
 
@@ -95,13 +100,15 @@ module Meta
 
       private
 
-      def filter_by(stage:, user_scope: false)
-        @properties.transform_values do |property|
-          property.find_schema(stage: stage, scope: user_scope)
-        end.filter do |name, schema|
-          schema.filter?
+        # 根据所示的关键字参数，过滤出符合条件的属性
+        # 注意，这里会结合自身的 locked_scope 考量
+        def filter_by(stage:, user_scope: false)
+          @properties.transform_values do |property|
+            property.find_schema(stage: stage, scope: user_scope)
+          end.filter do |name, schema|
+            schema.filter?
+          end
         end
-      end
 
       def resolve_property_value(object_value, name, property_schema)
         if property_schema.value?

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

@@ -40,13 +40,17 @@ module Meta
       def defined_scopes(stage:, defined_scopes_mapping:)
         defined_scopes_mapping ||= {}
 
-        schema_name = object_schema.properties.schema_name(stage)
-        return defined_scopes_mapping[schema_name] if defined_scopes_mapping.key?(schema_name)
+        if object_schema.properties.respond_to?(:schema_name)
+          # 只有命名实体才会被缓存
+          schema_name = object_schema.properties.schema_name(stage)
+          return defined_scopes_mapping[schema_name] if defined_scopes_mapping.key?(schema_name)
+        end
 
         defined_scopes_mapping[schema_name] = []
+        # 求解 defined_scopes，最终结果去重 + 排序
         defined_scopes = object_schema.properties.each.map do |name, property|
           property.defined_scopes(stage: stage, defined_scopes_mapping: defined_scopes_mapping)
-        end.flatten.uniq.sort
+        end.flatten.uniq.sort_by(&:name)
         defined_scopes_mapping[schema_name] = defined_scopes
         defined_scopes
       end

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

@@ -1,14 +1,18 @@
 # frozen_string_literal: true
 
 require_relative '../support/scope_matcher'
+require_relative '../../scope/utils'
 
 module Meta
   module JsonSchema
+    # TODO: 作为模块引入
     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
 
@@ -17,7 +21,9 @@ module Meta
       end
 
       def defined_scopes(**kwargs)
-        scope_matcher.defined_scopes
+        current = scope_matcher.defined_scopes
+        deep = schema.defined_scopes(**kwargs)
+        (current + deep).uniq
       end
 
       private
@@ -30,7 +36,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/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

@@ -43,7 +43,13 @@ module Meta
         codes.each { |code| @meta[:responses][code] = entity_schema }
       end
 
-      [:tags, :title, :description, :scope].each do |method_name|
+      def scope(scope)
+        scope = [scope] unless scope.is_a?(Array)
+
+        @meta[:scope] = scope
+      end
+
+      [:tags, :title, :description].each do |method_name|
         define_method(method_name) do |value|
           @meta[method_name] = value
         end

data/lib/meta/route_dsl/parameters_builder.rb

@@ -24,6 +24,7 @@ module Meta
         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,7 @@
 # frozen_string_literal: true
 
 require 'json'
-require_relative '../entity'
+require_relative '../entity' # TODO: 放在这里不太合适
 require_relative '../application/route'
 require_relative 'chain_builder'
 require_relative 'action_builder'

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

@@ -45,7 +45,7 @@ module Meta
             final_args.merge!(args)
           else
             extras = args.keys
-            raise "不接受额外的关键字参数：#{extras.join(', ')}" unless extras.empty?
+            raise ArgumentError, "不接受额外的关键字参数：#{extras.join(', ')}" unless extras.empty?
           end
         end
 

data/meta-api.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name          = "meta-api"
-  spec.version       = "0.1.0"
+  spec.version       = "0.1.2"
   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.0
+  version: 0.1.2
 platform: ruby
 authors:
 - yetrun
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-08-05 00:00:00.000000000 Z
+date: 2024-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hash_to_struct
@@ -81,6 +81,8 @@ files:
 - lib//meta/route_dsl/parameters_builder.rb
 - lib//meta/route_dsl/route_builder.rb
 - lib//meta/route_dsl/uniformed_params_builder.rb
+- lib//meta/scope/base.rb
+- lib//meta/scope/utils.rb
 - lib//meta/swagger_doc.rb
 - lib//meta/utils/kwargs/builder.rb
 - lib//meta/utils/kwargs/check.rb