meta-api 0.0.9 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3394a5e2d3b6dfd45f1478d8477426a4a947253d3252a050dc9c1d7cafd3c3d1
-  data.tar.gz: 98d12919b2adf824bec651ba5625076ddb7571962cdc66cee188b3b250fd1b24
+  metadata.gz: f5f1c4106f4106c1a3e69249e35f4efc02d4ca5d5981d4e32442c380f4228556
+  data.tar.gz: 7dc942b0a36759a0953a255b18a7c6c6312159365e9b829b48f223d0d83cd685
 SHA512:
-  metadata.gz: c1e80fecb3cf0bce148345660f19a8f44136b1e1647471e89aa9fb4d1c4f55a0ddf7ccb11fdc26ca7880c318173ed4f3254e0835d5bfd96e77048a301804d729
-  data.tar.gz: 16d7fdf0f82b89155eb0fc655e424d54ba5bf880c984dd322266afdb2952c4c34ff1ce2c83f8d174adcb086057d6c63aa7534b75defd4c3f7ff84f8a7f948ec0
+  metadata.gz: 275731f780c2e5eb3dcae314a5b7832504f053092eee8aa3eb1e8b85d7cce0f4fec33bf8f46626cb307d6c7c98e6ff0ee13bf100d6a4610099323d069968d7ae
+  data.tar.gz: f3f21b6e62503946e26471f9199809247d0ee3fafa13a2190e57aadb038b47cb19757ed08be4f2054e2b0151c2ed9f1cf4d737c007e133479395aa936d2a338b

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 更新日志
 
+## 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:` 选项。
+2. `type_conversion` 为 `false` 时不影响对象和数组类型的转化。
+3. 修复 `ref:` 嵌套造成的文档问题。
+4. 将 HTTP Method 的 scope 添加 `$` 符号前缀，如 `$get`、`$post` 等。
+5. `Meta.config` 去掉了 `default_locked_scope` 的配置项。
+
 ## 0.0.9（2023 年 7 月 22 日）
 
 1. JsonSchema 添加 before:、after: 选项，用于在过滤前后执行一些操作。

data/lib/meta/application/metadata.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
 require_relative 'parameters'
+require_relative 'responses'
 
 module Meta
   class Metadata
     module ExecutionMethods
       def parse_parameters(execution)
         parameters.filter(execution.request)
-        # TODO: 未捕获 JsonSchema::ValidationErrors 异常
+      rescue JsonSchema::ValidationErrors => e
+        raise Errors::ParameterInvalid.new(e.errors)
       end
 
       def parse_request_body(execution, discard_missing: false)
@@ -16,7 +18,7 @@ module Meta
           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.concat(["$#{method}"]), discard_missing: discard_missing }.compact
         )
       rescue JsonSchema::ValidationErrors => e
         raise Errors::ParameterInvalid.new(e.errors)
@@ -70,7 +72,7 @@ module Meta
       @tags = tags
       @parameters = parameters.is_a?(Parameters) ? parameters : Parameters.new(parameters)
       @request_body = request_body
-      @responses = responses || {} # || { 204 => nil }
+      @responses = responses.is_a?(Responses) ? responses : Responses.new(responses)
       @scope = scope
     end
 
@@ -88,7 +90,7 @@ module Meta
       operation_object[:parameters] = parameters.to_swagger_doc
 
       if request_body
-        schema = request_body.to_schema_doc(stage: :param, scope: self.scope + scope, schemas: schemas)
+        schema = request_body.to_schema_doc(stage: :param, scope: self.scope + scope, schema_docs_mapping: schemas)
         if schema || true
           operation_object[:requestBody] = {
             content: {
@@ -100,16 +102,7 @@ module Meta
         end
       end
 
-      operation_object[:responses] = responses.transform_values do |schema|
-        {
-          description: '', # description 属性必须存在
-          content: schema ? {
-            'application/json' => {
-              schema: schema.to_schema_doc(stage: :render, scope: self.scope + scope, schemas: schemas)
-            }
-          } : nil
-        }.compact
-      end unless responses.empty?
+      operation_object[:responses] = responses.to_swagger_doc(schemas, scope: self.scope + scope)
 
       operation_object.compact
     end

data/lib/meta/application/responses.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Meta
+  class Responses
+    extend Forwardable
+
+    attr_reader :responses
+
+    def initialize(responses = {})
+      @responses = responses || {}
+    end
+
+    def_delegators :@responses, :[], :empty?, :length, :keys
+
+    def to_swagger_doc(schemas, scope:)
+      if responses.empty?
+        { '200' => { description: '' } }
+      else
+        responses.transform_values do |schema|
+          {
+            description: '', # description 属性必须存在
+            content: schema ? {
+              'application/json' => {
+                schema: schema.to_schema_doc(stage: :render, scope: scope, schema_docs_mapping: schemas)
+              }
+            } : nil
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/meta/application/route.rb

@@ -39,7 +39,7 @@ module Meta
     end
 
     def generate_operation_doc(schemas)
-      meta.generate_operation_doc(schemas, scope: [method])
+      meta.generate_operation_doc(schemas, scope: ["$#{method}"])
     end
   end
 end

data/lib/meta/config.rb

@@ -4,7 +4,6 @@ require 'hash_to_struct'
 
 module Meta
   DEFAULT_OPTIONS = {
-    default_locked_scope: nil,
     json_schema_user_options: {},
     json_schema_param_stage_user_options: {},
     json_schema_render_stage_user_options: {}

data/lib/meta/entity.rb

@@ -14,45 +14,13 @@ module Meta
       def inherited(base)
         base.instance_eval do
           @schema_builder = JsonSchema::ObjectSchemaBuilder.new
-          @schema_builder.schema_name(proc { |locked_scope, stage|
-            generate_schema_name(locked_scope, stage)
-          })
+          @schema_builder.schema_name(self.name) if self.name
         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
-
-      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
-end
+end

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

@@ -5,10 +5,75 @@ require_relative '../schemas/properties'
 module Meta
   module JsonSchema
     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
+
+        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
+          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)
+          @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 = common_options.merge(options)
+          object_schema_builder.property(name, options, &block)
+        end
+      end
+
+      attr_reader :properties
+
       def initialize(options = {}, &)
         raise 'type 选项必须是 object' if !options[:type].nil? && options[:type] != 'object'
 
-        @properties = {}
+        @properties = {} # 所有的属性已经生成
         @required = []
         @validations = {}
 
@@ -23,22 +88,12 @@ module Meta
         instance_exec(&) if block_given?
       end
 
-      # 设置 schema_name.
-      #
-      # 一、可以传递一个块，该块会接收 locked_scope 参数，需要返回一个带有 param 和 render 键的 Hash.
-      # 二、可以传递一个 Hash，它包含 param 和 render 键。
-      # 三、可以传递一个字符串。
-      def schema_name(schema_name_resolver)
-        if schema_name_resolver.is_a?(Proc)
-          @schema_name_resolver = schema_name_resolver
-        elsif schema_name_resolver.is_a?(Hash)
-          @schema_name_resolver = proc { |stage, locked_scopes| schema_name_resolver[stage] }
-        elsif schema_name_resolver.is_a?(String)
-          @schema_name_resolver = proc { |stage, locked_scopes| schema_name_resolver }
-        elsif schema_name_resolver.nil?
-          @schema_name_resolver = proc { nil }
+      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
-          raise TypeError, "schema_name_resolver 必须是一个 Proc、Hash 或 String，当前是：#{schema_name_resolver.class}"
+          @schema_name
         end
       end
 
@@ -55,52 +110,63 @@ module Meta
         instance_exec(&proc)
       end
 
-      def to_schema(locked_options = nil)
-        ObjectSchema.new(properties: @properties, options: @options, locked_options: locked_options, schema_name_resolver: @schema_name_resolver)
+      def with_common_options(common_options, &block)
+        WithCommonOptions.new(self, common_options, &block)
       end
 
-      def lock(key, value)
-        locked(key => value)
+      def scope(scope, options = {}, &)
+        with_common_options(**options, scope: scope, &)
       end
 
-      def locked(options)
-        Locked.new(self, options)
+      def params(options = {}, &block)
+        with_common_options(**options, render: false, &block)
       end
 
-      private
+      def render(options = {}, &block)
+        with_common_options(**options, params: false, &block)
+      end
 
-      def apply_array_scope?(options, block)
-        options[:type] == 'array' && (options[:items] || block)
+      def merge(schema_builder)
+        schema_builder = schema_builder.schema_builder if schema_builder.respond_to?(:schema_builder)
+
+        @properties.merge!(schema_builder.properties)
       end
 
-      def apply_object_scope?(options, block)
-        (options[:type] == 'object' || block) && (options[:properties] || block)
+      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 method_missing(method, *args)
-        if method =~ /^lock_(\w+)$/
-          key = Regexp.last_match(1)
-          lock(key.to_sym, *args)
-        else
-          super
+      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
 
-      class Locked
-        attr_reader :builder, :locked_options
+      private
 
-        def initialize(builder, locked_options)
-          @builder = builder
-          @locked_options = locked_options
-        end
+      def apply_array_scope?(options, block)
+        options[:type] == 'array' && (options[:items] || block)
+      end
 
-        # 当调用 Entity.locked 方法后，生成 schema 的方法会掉到这里面来。
-        # 在生成 schema 时，locked_options 会覆盖；当生成 schema 文档时，由于缺失 schema_name 的
-        # 信息，故而 schema_name 相关的影响就消失不见了。
-        def to_schema
-          builder.to_schema(locked_options)
-        end
+      def apply_object_scope?(options, block)
+        (options[:type] == 'object' || block) && (options[:properties] || block)
       end
     end
   end
-end
+end

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

@@ -14,11 +14,7 @@ module Meta
           permit_extras true
 
           key :ref, alias_names: [:using], normalizer: ->(entity) {
-            if Meta.config.default_locked_scope && entity.is_a?(Class) && entity < Meta::Entity
-              entity.locked(scope: Meta.config.default_locked_scope)
-            else
-              entity
-            end
+            entity
           }
           key :dynamic_ref, alias_names: [:dynamic_using], normalizer: ->(value) { value.is_a?(Proc) ? { resolve: value } : value }
         end
@@ -34,7 +30,7 @@ module Meta
           elsif apply_object_schema?(options, block)
             ObjectSchemaBuilder.new(options, &block).to_schema
           else
-            StagingSchema.build_from_options(options)
+            BaseSchema.new(options)
           end
         end
 

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

@@ -3,6 +3,8 @@
 module Meta
   module JsonSchema
     class ArraySchema < BaseSchema
+      extend Forwardable
+
       attr_reader :items
 
       def initialize(items, options = {})
@@ -22,10 +24,19 @@ module Meta
         schema
       end
 
+      def_delegator :@items, :defined_scopes
+
       private
 
       def filter_internal(array_value, user_options)
-        raise ValidationError.new('参数应该传递一个数组') unless array_value.respond_to?(:each_with_index)
+        if array_value.respond_to?(:each_with_index)
+          array_value = array_value
+        elsif array_value.respond_to?(:to_a)
+          array_value = array_value.to_a
+        else
+          raise ValidationError.new('参数应该传递一个数组或者数组 Like 的对象（实现了 each_with_index 或者 to_a 方法）')
+        end
+
         array_value.each_with_index.map do |item, index|
           begin
             @items.filter(item, user_options)

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

@@ -89,7 +89,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,15 +103,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
 
@@ -123,7 +130,8 @@ module Meta
       #
       # 选项：
       # - stage: 传递 :param 或 :render
-      # - schemas: 用于保存已经生成的 Schema
+      # - schema_docs_mapping: 用于保存已经生成的 Schema
+      # - defined_scopes_mapping: 用于缓存已经定义的 scopes
       # - presenter: 兼容 Grape 框架的实体类
       def to_schema_doc(**user_options)
         return Presenters.to_schema_doc(options[:presenter], options) if options[:presenter]

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require_relative 'properties'
+
+module Meta
+  module JsonSchema
+    class NamedProperties < Properties
+      attr_reader :schema_base_name
+
+      def initialize(properties, schema_base_name)
+        super(properties)
+
+        raise TypeError, "schema_name 必须是一个 String，当前是：#{schema_base_name.class}" unless schema_base_name.is_a?(String)
+        raise ArgumentError, 'schema_name 不能为 nil 或空字符串' if schema_base_name.nil? || schema_base_name.empty?
+
+        # 修正 base_name，确保其不包含 Entity 后缀
+        schema_base_name = schema_base_name.delete_suffix('Entity') if schema_base_name&.end_with?('Entity')
+        @schema_base_name = schema_base_name
+      end
+
+      def schema_name(stage)
+        if stage == :render
+          "#{schema_base_name}Entity"
+        elsif stage == :param
+          "#{schema_base_name}Params"
+        else
+          raise ArgumentError, "stage 必须是 :render 或 :param，当前是：#{stage}"
+        end
+      end
+
+      def merge(other_properties)
+        raise UnsupportedError, 'NamedProperties 不支持 merge 操作'
+      end
+    end
+  end
+end

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

@@ -1,61 +1,79 @@
 # frozen_string_literal: true
 
 require_relative '../../utils/kwargs/check'
+require_relative 'named_properties'
 
 module Meta
   module JsonSchema
     class ObjectSchema < BaseSchema
-      attr_reader :properties, :locked_options
+      attr_reader :properties
+      # 只有 ObjectSchema 对象才有 locked_options，因为 locked_options 多是用来锁定属性的行为的，包括：
+      # scope:、discard_missing:、exclude: 等
+      attr_reader :locked_options
 
+      # stage 和 scope 选项在两个 CHECKER 下都用到了
       USER_OPTIONS_CHECKER = Utils::KeywordArgs::Builder.build do
-        permit_extras true
-
+        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: nil, options: {}, locked_options: {}, schema_name_resolver: proc { nil })
+      def initialize(properties:, options: {}, locked_options: {})
+        raise ArgumentError, 'properties 必须是 Properties 实例' unless properties.is_a?(Properties)
+
         super(options)
 
         @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 || {})
-        @schema_name_resolver = schema_name_resolver || proc { nil }
-      end
-
-      # 复制一个新的 ObjectSchema，只有 options 不同
-      def dup(options)
-        self.class.new(
-          properties: properties,
-          options: options,
-          locked_options: locked_options,
-          schema_name_resolver: @schema_name_resolver
-        )
       end
 
       def filter(object_value, user_options = {})
         # 合并 user_options
         user_options = USER_OPTIONS_CHECKER.check(user_options)
-        user_options = merge_user_options(user_options, locked_options) if locked_options
+        user_options = self.class.merge_user_options(user_options, locked_options) if locked_options
         super
       end
 
-      # 合并其他的属性，并返回一个新的 ObjectSchema
-      def merge_other_properties(properties)
-        ObjectSchema.new(properties: self.properties.merge(properties))
+      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
 
-      def resolve_name(stage)
+      def resolve_name(stage, user_scopes, defined_scopes)
+        raise ArgumentError, 'stage 不能为 nil' if stage.nil?
+
+        # 先合成外面传进来的 scope
         locked_scopes = (locked_options || {})[:scope] || []
-        @schema_name_resolver.call(stage, locked_scopes)
+        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 = USER_OPTIONS_CHECKER.check(user_options)
-        user_options = merge_user_options(user_options, locked_options) if locked_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]
@@ -80,7 +98,7 @@ module Meta
         @properties.filter(object_value, user_options)
       end
 
-      def merge_user_options(user_options, locked_options)
+      def self.merge_user_options(user_options, locked_options)
         user_options.merge(locked_options) do |key, user_value, locked_value|
           if key == :scope
             user_value + locked_value

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

@@ -11,7 +11,11 @@ module Meta
         @properties = properties
       end
 
+      # user_options 包括 stage, scope, extra_properties, discard_missing, exclude、execution、user_data
       def filter(object_value, user_options = {})
+        # 首先，要将 object_value 转化为 ObjectWrapper
+        object_value = JsonObject.wrap(object_value)
+
         # 第一步，根据 user_options[:scope] 需要过滤一些字段
         stage = user_options[:stage]
         # 传递一个数字；因为 scope 不能包含数字，这里传递一个数字，使得凡是配置 scope 的属性都会被过滤
@@ -26,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
@@ -40,6 +44,12 @@ 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
@@ -65,6 +75,13 @@ 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)
@@ -78,7 +95,7 @@ module Meta
       end
 
       # 程序中有些地方用到了这三个方法
-      def_delegators :@properties, :empty?, :key?, :[]
+      def_delegators :@properties, :empty?, :key?, :[], :each
 
       def merge(properties)
         self.class.new(@properties.merge(properties.instance_eval { @properties }))
@@ -101,7 +118,7 @@ module Meta
       def resolve_property_value(object_value, name, property_schema)
         if property_schema.value?
           nil
-        elsif object_value.is_a?(Hash) || object_value.is_a?(ObjectWrapper)
+        elsif object_value.is_a?(Hash) || object_value.is_a?(JsonObject)
           object_value.key?(name.to_s) ? object_value[name.to_s] : object_value[name.to_sym]
         else
           raise "不应该还有其他类型了，已经在类型转换中将其转换为 Meta::JsonSchema::ObjectWrapper 了"

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

@@ -5,31 +5,61 @@ require_relative 'base_schema'
 module Meta
   module JsonSchema
     class RefSchema < BaseSchema
-      attr_reader :schema
+      attr_reader :object_schema
+
+      def initialize(object_schema, options = {})
+        raise ArgumentError, 'object_schema 必须是一个 ObjectSchema' unless object_schema.is_a?(ObjectSchema)
 
-      def initialize(schema, options = {})
         super(options)
-        @schema = schema
+        @object_schema = object_schema
       end
 
       def filter(value, user_options = {})
         value = super
-        schema.filter(value, user_options)
+        object_schema.filter(value, user_options)
       end
 
       def to_schema_doc(user_options)
-        schema_name = schema.resolve_name(user_options[:stage])
+        raise '引用的 ObjectSchema 没有包含命名逻辑，无法生成文档' unless object_schema.naming?
 
-        # 首先将 Schema 写进 schemas 选项中去
-        schema_components = user_options[:schemas]
+        # 首先，要求出 defined_scopes
+        defined_scopes = self.defined_scopes(stage: user_options[:stage], defined_scopes_mapping: user_options[:defined_scopes_mapping])
+        # 然后，求出 schema_name
+        schema_name = object_schema.resolve_name(user_options[:stage], user_options[:scope], defined_scopes)
+        # 接着将 Schema 写进 schemas 选项中去
+        schema_components = user_options[:schema_docs_mapping] || {}
         unless schema_components.key?(schema_name)
           schema_components[schema_name] = nil # 首先设置 schemas 防止出现无限循环
-          schema_components[schema_name] = schema.to_schema_doc(**user_options) # 原地修改 schemas，无妨
+          schema_components[schema_name] = object_schema.to_schema_doc(**user_options) # 原地修改 schemas，无妨
         end
 
-        # 返回的是 $ref 结构
+        # 最后，返回这个 $ref 结构
         { '$ref': "#/components/schemas/#{schema_name}" }
       end
+
+      def defined_scopes(stage:, defined_scopes_mapping:)
+        defined_scopes_mapping ||= {}
+
+        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 = object_schema.properties.each.map do |name, property|
+          property.defined_scopes(stage: stage, defined_scopes_mapping: defined_scopes_mapping)
+        end.flatten.uniq.sort
+        defined_scopes_mapping[schema_name] = defined_scopes
+        defined_scopes
+      end
+
+      private
+
+      # # TODO: 这种带有组合方式的 Schema，让我联想到，每次 BaseSchema 新增一个方法都要在子 Schema 中加一遍，很烦！
+      # def defined_scopes
+      #   schema.defined_scopes
+      # end
     end
   end
 end

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

@@ -1,39 +1,38 @@
 # frozen_string_literal: true
 
+require_relative '../support/scope_matcher'
+
 module Meta
   module JsonSchema
     class ScopingSchema < BaseSchema
-      attr_reader :on, :schema
-
-      def initialize(required_scope: [], schema:)
-        raise ArgumentError, 'required_scope 选项不可传递 nil' if required_scope.nil?
-        required_scope = [required_scope] unless required_scope.is_a?(Array)
+      attr_reader :scope_matcher, :schema
 
-        @on = required_scope
+      def initialize(scope_matcher_options: , schema:)
+        @scope_matcher = ScopeMatcher.new(scope_matcher_options)
         @schema = schema
       end
 
       def scoped(user_scopes)
-        return schema if (on - user_scopes).empty? # required_scopes 应被消耗殆尽
+        @scope_matcher.match?(user_scopes) ? schema : unsupported_schema(user_scopes)
+      end
 
-        UnsupportedSchema.new(:on, user_scopes)
+      def defined_scopes(**kwargs)
+        current = scope_matcher.defined_scopes
+        deep = schema.defined_scopes(**kwargs)
+        (current + deep).uniq
       end
 
-      STAGING_SCHEMA_OPTIONS = Utils::KeywordArgs::Builder.build do
-        permit_extras true
+      private
 
-        # TODO: 如果我想把 on 改名为 require_scopes，关键字参数的机制是否支持？
-        key :on, alias_names: [:scope], default: [], normalizer: ->(required_scopes) {
-          required_scopes = [] if required_scopes.nil?
-          required_scopes = [required_scopes] unless required_scopes.is_a?(Array)
-          required_scopes
-        }
+      def unsupported_schema(user_scopes)
+        UnsupportedSchema.new(:scope, user_scopes)
       end
+
       def self.build_from_options(options, build_schema)
-        options = STAGING_SCHEMA_OPTIONS.check(options)
-        required_scope = options.delete(:on) || []
+        options = options.dup
+        scope_matcher_options = options.delete(:scope)
         schema = build_schema.call(options)
-        schema = ScopingSchema.new(required_scope: required_scope, schema: schema) unless required_scope.empty?
+        schema = ScopingSchema.new(scope_matcher_options: scope_matcher_options, schema: schema) if scope_matcher_options
         schema
       end
     end

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

@@ -9,16 +9,14 @@ module Meta
   module JsonSchema
     # 内含 param_schema, render_schema, default_schema，分别用于不同的阶段。
     class StagingSchema < BaseSchema
-      attr_reader :param_schema, :render_schema, :default_schema
+      attr_reader :param_schema, :render_schema
 
-      def initialize(param_schema:, render_schema:, default_schema:)
+      def initialize(param_schema:, render_schema:)
         raise ArgumentError, 'param_schema 选项重复提交为 StagingSchema' if param_schema.is_a?(StagingSchema)
         raise ArgumentError, 'render_schema 选项重复提交为 StagingSchema' if render_schema.is_a?(StagingSchema)
-        raise ArgumentError, 'default_schema 选项重复提交为 StagingSchema' if default_schema.is_a?(StagingSchema)
 
         @param_schema = param_schema
         @render_schema = render_schema
-        @default_schema = default_schema
       end
 
       def filter(value, user_options = {})
@@ -27,7 +25,7 @@ module Meta
         elsif user_options[:stage] == :render
           render_schema.filter(value, user_options)
         else
-          default_schema.filter(value, user_options)
+          raise ArgumentError, "stage 选项必须是 :param 或 :render"
         end
       end
 
@@ -37,10 +35,14 @@ module Meta
         elsif stage == :render
           render_schema
         else
-          default_schema
+          raise ArgumentError, "stage 选项必须是 :param 或 :render"
         end
       end
 
+      def defined_scopes(stage:, **kwargs)
+        staged(stage).defined_scopes(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
@@ -48,9 +50,8 @@ module Meta
         else
           StagingSchema.new(
             param_schema: param_opts ? ScopingSchema.build_from_options(param_opts, build_schema) : UnsupportedSchema.new(:stage, :param),
-            render_schema: render_opts ? ScopingSchema.build_from_options(render_opts, build_schema) : UnsupportedSchema.new(:stage, :render),
-            default_schema: ScopingSchema.build_from_options(common_opts, build_schema),
-            )
+            render_schema: render_opts ? ScopingSchema.build_from_options(render_opts, build_schema) : UnsupportedSchema.new(:stage, :render)
+          )
         end
       end
     end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# 将 Ruby 类型包装成 JsonObject 类型，以便可以通过 [key] 访问。同时，保留其他方法的调用，将其转发到原始对象上。
+module Meta
+  module JsonSchema
+    class JsonObject
+      def initialize(target)
+        @target = target
+      end
+
+      def __target__
+        @target
+      end
+
+      def key?(key)
+        @target.respond_to?(key)
+      end
+
+      def [](key)
+        @target.__send__(key)
+      end
+
+      def method_missing(method, *args)
+        @target.__send__(method, *args)
+      end
+
+      def self.wrap(target)
+        case target
+        when JsonObject, Hash
+          target
+        else
+          new(target)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Meta
+  module JsonSchema
+    class ScopeMatcher
+      attr_reader :defined_scopes
+
+      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)
+
+        @match_type, @defined_scopes = query_clause.first
+      end
+
+      def match?(scopes)
+        return false if scopes.empty?
+
+        case @match_type
+        when :some_of
+          (@defined_scopes & scopes).any?
+        when :all_of
+          (@defined_scopes - scopes).empty?
+        else
+          raise "Unknown match type: #{@match_type}"
+        end
+      end
+    end
+  end
+end

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

@@ -1,31 +1,10 @@
 # frozen_string_literal: true
 
 require 'bigdecimal'
+require_relative 'json_object'
 
 module Meta
   module JsonSchema
-    class ObjectWrapper
-      def initialize(target)
-        @target = target
-      end
-
-      def __target__
-        @target
-      end
-
-      def key?(key)
-        @target.respond_to?(key)
-      end
-
-      def [](key)
-        @target.__send__(key)
-      end
-
-      def method_missing(method, *args)
-        @target.__send__(method, *args)
-      end
-    end
-
     module TypeConverter
       # 定义客户类型对应的 Ruby 类型
       @definity_types = {
@@ -34,7 +13,7 @@ module Meta
         'number' => [Integer, Float, BigDecimal],
         'string' => [String],
         'array' => [Array],
-        'object' => [Hash, ObjectWrapper]
+        'object' => [Hash, JsonObject]
       }
 
       # 定义从 Ruby 类型转化为对应类型的逻辑
@@ -101,7 +80,7 @@ module Meta
             raise TypeConvertError, I18n.t(:'json_schema.errors.type_convert.object', value: value, real_type: I18n.t(:'json_schema.type_names.array'))
           end
 
-          ObjectWrapper.new(value)
+          JsonObject.new(value)
         end
       }
 

data/lib/meta/route_dsl/meta_builder.rb

@@ -43,7 +43,16 @@ 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)
+        unless scope.all? { |s| s.start_with?('$') }
+          raise ArgumentError, 'namespace 和 route 中声明的 scope 必须是全局 scope（以 $ 开头）'
+        end
+
+        @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/swagger_doc.rb

@@ -5,7 +5,7 @@ module Meta
     class << self
       def generate(application, info: {}, servers: [])
         paths_and_routes = get_paths_and_routes!(application)
-        return generate_from_paths_and_routes(paths_and_routes, info: info, servers: servers)
+        generate_from_paths_and_routes(paths_and_routes, info: info, servers: servers)
       end
 
       def generate_from_paths_and_routes(paths_and_routes, info: {}, servers: [])
@@ -62,28 +62,5 @@ module Meta
         store_routes
       end
     end
-
-    class Path
-      def initialize(parts = [])
-        @parts = parts.freeze
-      end
-
-      def append(part)
-        part = part[1..-1] if part.start_with?('/')
-        parts = part.split('/')
-
-        self.class.new(@parts + parts)
-      end
-
-      def to_s
-        '/' + @parts.join('/')
-      end
-
-      def self.from_string(path)
-        path = path[1..-1] if path.start_with?('/')
-        parts = path.split('/')
-        self.class.new(parts)
-      end
-    end
   end
 end

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

@@ -58,20 +58,20 @@ module Meta
         def initialize(name:, normalizer: DEFAULT_TRANSFORMER, validator: nil, default: nil, alias_names: [])
           @key_name = name
           @consumer_names = [name] + alias_names
-          # TODO: 当且仅当 value 是 nil 时，才使用 default
-          @normalizer = default ? ->(value) { normalizer.call(value || default) } : normalizer
+          @default_value = default
+          @normalizer = normalizer
           @validator = validator
         end
 
         def consume(final_args, args)
           @consumer_names.each do |name|
-            return true if consume_name(final_args, args, name)
+            return if consume_name(final_args, args, name)
           end
-          return false
+
+          final_args[@key_name] = @default_value unless @default_value.nil?
         end
 
         def consume_name(final_args, args, consumer_name)
-          # TODO: default 未起作用
           if args.key?(consumer_name)
             value = @normalizer.call(args.delete(consumer_name))
             @validator.call(value) if @validator

data/lib/meta/utils/route_dsl_builders.rb

@@ -10,7 +10,7 @@ module Meta
             final_options[:parameters] = options1[:parameters].merge(options2[:parameters])
           end
           if options1[:request_body].is_a?(Meta::JsonSchema::ObjectSchema) && options2[:request_body].is_a?(Meta::JsonSchema::ObjectSchema)
-            final_options[:request_body] = options1[:request_body].merge_other_properties(options2[:request_body].properties)
+            final_options[:request_body] = options1[:request_body].properties.merge(options2[:request_body].properties)
           end
           if options1[:responses] && options2[:responses]
             final_options[:responses] = options1[:responses].merge(options2[:responses])

data/meta-api.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name          = "meta-api"
-  spec.version       = "0.0.9"
+  spec.version       = "0.1.1"
   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.0.9
+  version: 0.1.1
 platform: ruby
 authors:
 - yetrun
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-22 00:00:00.000000000 Z
+date: 2024-06-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hash_to_struct
@@ -42,6 +42,7 @@ files:
 - lib//meta/application/metadata.rb
 - lib//meta/application/parameters.rb
 - lib//meta/application/path_matching_mod.rb
+- lib//meta/application/responses.rb
 - lib//meta/application/route.rb
 - lib//meta/config.rb
 - lib//meta/entity.rb
@@ -56,6 +57,7 @@ files:
 - lib//meta/json_schema/schemas/array_schema.rb
 - lib//meta/json_schema/schemas/base_schema.rb
 - lib//meta/json_schema/schemas/dynamic_schema.rb
+- lib//meta/json_schema/schemas/named_properties.rb
 - lib//meta/json_schema/schemas/object_schema.rb
 - lib//meta/json_schema/schemas/properties.rb
 - lib//meta/json_schema/schemas/ref_schema.rb
@@ -63,8 +65,10 @@ files:
 - lib//meta/json_schema/schemas/staging_schema.rb
 - lib//meta/json_schema/schemas/unsupported_schema.rb
 - lib//meta/json_schema/support/errors.rb
+- lib//meta/json_schema/support/json_object.rb
 - lib//meta/json_schema/support/presenters.rb
 - lib//meta/json_schema/support/schema_options.rb
+- lib//meta/json_schema/support/scope_matcher.rb
 - lib//meta/json_schema/support/type_converter.rb
 - lib//meta/json_schema/support/validators.rb
 - lib//meta/load_i18n.rb