meta-api 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5f1c4106f4106c1a3e69249e35f4efc02d4ca5d5981d4e32442c380f4228556
-  data.tar.gz: 7dc942b0a36759a0953a255b18a7c6c6312159365e9b829b48f223d0d83cd685
+  metadata.gz: 176e67a6d2a121ef7841ec614a2104f7f5f201c863ea88eb805e450b9ab13ee4
+  data.tar.gz: bd9be253deb822db45e2bf1c0548467652155dbf39255d49709da7b7d5a56726
 SHA512:
-  metadata.gz: 275731f780c2e5eb3dcae314a5b7832504f053092eee8aa3eb1e8b85d7cce0f4fec33bf8f46626cb307d6c7c98e6ff0ee13bf100d6a4610099323d069968d7ae
-  data.tar.gz: f3f21b6e62503946e26471f9199809247d0ee3fafa13a2190e57aadb038b47cb19757ed08be4f2054e2b0151c2ed9f1cf4d737c007e133479395aa936d2a338b
+  metadata.gz: 2d1e5c80f3699d00bd529b74da7881eb559c089ab0bbb088560599453eea2972dc38dd082d991fc0be5e2815509987e8a3176d4d3fb0b041d35ae4ec5682c665
+  data.tar.gz: 59fcbd0be04d0d94a768f5b63e46a5ffcbc3a0a67ed89959ff957f8be4d1f9b7d04551cc090f6cc3a031effe45cebcb369d4a10f31fbc7a5811e2760a7f0b335

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,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/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

@@ -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
@@ -63,9 +64,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
@@ -73,6 +90,8 @@ module Meta
       def initialize(options = {}, &)
         raise 'type 选项必须是 object' if !options[:type].nil? && options[:type] != 'object'
 
+        @schema_cache = {} # 用于缓存已经生成的 schema，重复利用
+
         @properties = {} # 所有的属性已经生成
         @required = []
         @validations = {}
@@ -82,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?
@@ -99,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
@@ -123,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)
@@ -132,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,18 +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
@@ -36,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,22 +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, :allowable
-        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` 包含了转换器、验证器、文档、选项。
       #
       # 由于本对象可继承，基于不同的继承可分别表示基本类型、对象和数组，所以该属
@@ -47,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?
@@ -58,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]
@@ -139,7 +119,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

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require_relative '../../utils/kwargs/check'
 require_relative 'named_properties'
 
 module Meta
@@ -11,27 +10,6 @@ module Meta
       # scope:、discard_missing:、exclude: 等
       attr_reader :locked_options
 
-      # 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 :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 :schema_docs_mapping, :defined_scopes_mapping
-      end
-
       def initialize(properties:, options: {}, locked_options: {})
         raise ArgumentError, 'properties 必须是 Properties 实例' unless properties.is_a?(Properties)
 
@@ -39,16 +17,29 @@ 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 = 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]
+        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 +48,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
-
-      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

@@ -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
 
@@ -101,19 +94,25 @@ 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
 
       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,19 +47,13 @@ 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
-
-      private
-
-      # # TODO: 这种带有组合方式的 Schema，让我联想到，每次 BaseSchema 新增一个方法都要在子 Schema 中加一遍，很烦！
-      # def defined_scopes
-      #   schema.defined_scopes
-      # end
     end
   end
 end