meta-api 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5f1c4106f4106c1a3e69249e35f4efc02d4ca5d5981d4e32442c380f4228556
-  data.tar.gz: 7dc942b0a36759a0953a255b18a7c6c6312159365e9b829b48f223d0d83cd685
+  metadata.gz: 55ec631feb0038911007c4b1de6ca26fdf595ea84c41eecac046e417ff90a2e2
+  data.tar.gz: e384752c6ce459cb38adb4123078f10ad835c8f75a73256fddb1af02a8bac3b0
 SHA512:
-  metadata.gz: 275731f780c2e5eb3dcae314a5b7832504f053092eee8aa3eb1e8b85d7cce0f4fec33bf8f46626cb307d6c7c98e6ff0ee13bf100d6a4610099323d069968d7ae
-  data.tar.gz: f3f21b6e62503946e26471f9199809247d0ee3fafa13a2190e57aadb038b47cb19757ed08be4f2054e2b0151c2ed9f1cf4d737c007e133479395aa936d2a338b
+  metadata.gz: 19c21dc3c99bebf4adfaea519ffb44d901481c8b88349b1b87677e3155a1c5e75e4c1e639596f589a28c32192e3ed10330f7d3b85dbc4e7238af73b0d8c996ef
+  data.tar.gz: 3903b5879a3d4dc1092a32b41aa17891434363089a48225acef22267ad6a56416ba7576c6de6ebb4bb8bbb50ebe2bebc7cb5592cf3265bccafe0e3c98e3c670c

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 更新日志
 
+## 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` 方法，用于更有效地组织字段。

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,7 +14,12 @@ 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
 
@@ -23,4 +28,4 @@ module Meta
       end
     end
   end
-end
+end

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

@@ -63,9 +63,25 @@ module Meta
         end
 
         def property(name, options = {}, &block)
-          options = common_options.merge(options)
+          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
@@ -138,21 +154,21 @@ module Meta
       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
+        # 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

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
@@ -139,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: {})
@@ -49,6 +61,18 @@ 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
@@ -57,31 +81,39 @@ module Meta
         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
+        base_schema_name = properties.schema_name(stage)
 
-      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]
+        # 将调用转移到 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

@@ -44,12 +44,6 @@ module Meta
           value = resolve_property_value(object_value, name, property_schema)
 
           begin
-            # 如果 property_schema 是 RefSchema，则局部的 scope 不会传递下去
-            if property_schema.is_a?(RefSchema)
-              # 只接受全局的 scope，其以 $ 符合开头
-              new_scopes = user_options[:scope].find_all { |scope| scope.start_with?('$') }
-              user_options = user_options.merge(scope: new_scopes)
-            end
             object[name] = property_schema.filter(value, **user_options, object_value: object_value)
           rescue JsonSchema::ValidationErrors => e
             cause = e.cause || e if cause.nil? # 将第一次出现的错误作为 cause
@@ -75,16 +69,9 @@ module Meta
         end
       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
-
       # 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
@@ -94,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
 
@@ -107,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

@@ -47,9 +47,10 @@ module Meta
         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
 
@@ -32,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

@@ -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

@@ -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.1"
+  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.1
+  version: 0.1.2
 platform: ruby
 authors:
 - yetrun
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-01 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