meta-api 0.0.8 → 0.1.0

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

@@ -5,11 +5,35 @@ require_relative '../support/schema_options'
 
 module Meta
   module JsonSchema
+    # 表示一个基本类型的 Schema，或继承自该类表示一个拥有其他扩展能力的 Schema.
+    #
+    # 该类包含了通用 JsonSchema 思维的基本逻辑，比如 stage 和 scope. 其他 Schema 类应当主动地继
+    # 承自该类，这样就会自动获得 stage 和 scope 的能力。
+    #
+    # 该类剩余的逻辑是提供一个 `options` 属性，用于描述该 Schema. 因此，直接实例化该类可以用于表示
+    # 基本类型，而继承该类可以用于表示还有内部递归处理的对象和数组类型。这时，应当在子类的构造函数中调
+    # 用父类的构造方法，以便初始化 `options` 属性。并且在子类中重写 `filter_internal` 方法，实现
+    # 内部递归处理的逻辑。这种模式的案例主要是 `ObjectSchema` 和 `ArraySchema`.
+    #
+    # 如果是组合模式，也应当继承自该类，以便获得 stage 和 scope 的能力。但是，组合模式的 `options`
+    # 调用是非法的，因此不应当在构造函数中调用父类的构造方法。此时 options 为 nil，这样用到 options
+    # 的地方都会抛出异常（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 :param, :render
+        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` 包含了转换器、验证器、文档、选项。
@@ -22,25 +46,22 @@ module Meta
       attr_reader :options
 
       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
       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
+      def filter?
+        true
       end
 
       def filter(value, user_options = {})
         user_options = USER_OPTIONS_CHECKER.check(user_options)
 
-        value = resolve_value(user_options) if options[:value]
+        value = value_callback(user_options) if options[:value]
+        value = before_callback(value, user_options) if options[:before]
         value = JsonSchema::Presenters.present(options[:presenter], value) if options[:presenter]
         value = resolve_default_value(options[:default]) if value.nil? && options.key?(:default)
         value = options[:convert].call(value) if options[:convert]
@@ -59,35 +80,55 @@ module Meta
         # 第二步，做校验。
         validate!(value, options) unless user_options[:validation] == false
 
+        # 第三步，如果存在内部属性，递归调用。
+        value = filter_internal(value, user_options) unless value.nil?
+
+        # 最后，返回 value
+        value = after_callback(value, user_options) if options[:after]
         value
       end
 
-      def value?
-        options[:value] != nil
+      # 返回能够处理 scope 和 stage 的 schema（可以是 self），否则应返回 UnsupportedStageSchema 或 nil.
+      def find_schema(scope:, stage:)
+        staged(stage)&.scoped(scope)
       end
 
-      def resolve_value(user_options)
-        value_proc = options[:value]
-        if value_proc.lambda?
-          value_proc_params = []
-          value_proc_params << user_options[:object_value] if value_proc.arity >= 1
-          value_proc_params << user_options[:user_data] if value_proc.arity >= 2
-        else
-          value_proc_params = [user_options[:object_value], user_options[:user_data]]
-        end
+      # 返回能够处理 stage 的 schema（可以是 self），否则返回 UnsupportedStageSchema.
+      def staged(stage)
+        self
+      end
 
-        if user_options[:execution]
-          user_options[:execution].instance_exec(*value_proc_params, &value_proc)
+      # 返回能够处理 scope 的 schema（可以是 self），否则返回 nil.
+      def scoped(scope)
+        self
+      end
+
+      def defined_scopes(stage:, defined_scopes_mapping:)
+        []
+      end
+
+      # 执行 if: 选项，返回 true 或 false
+      def if?(user_options)
+        return true if options[:if].nil?
+
+        execution = user_options[:execution]
+        if execution
+          execution.instance_exec(&options[:if])
         else
-          value_proc.call(*value_proc_params)
+          options[:if]&.call
         end
       end
 
+      def value?
+        options[:value] != nil
+      end
+
       # 生成 Swagger 文档的 schema 格式。
       #
       # 选项：
       # - 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]
@@ -106,22 +147,51 @@ module Meta
 
       private
 
-        def validate!(value, stage_options)
-          stage_options.each do |key, option|
-            validator = JsonSchema::Validators[key]
-            validator&.call(value, option, stage_options)
-          end
+      def validate!(value, stage_options)
+        stage_options.each do |key, option|
+          validator = JsonSchema::Validators[key]
+          validator&.call(value, option, stage_options)
         end
+      end
 
-        def resolve_default_value(default_resolver)
-          if default_resolver.respond_to?(:call)
-            default_resolver.call
-          elsif default_resolver.respond_to?(:dup)
-            default_resolver.dup
-          else
-            default_resolver
-          end
+      def resolve_value(value, user_options, value_proc, arguments)
+        if value_proc.lambda?
+          value_proc_params = arguments[0...value_proc.arity]
+        else
+          value_proc_params = arguments
+        end
+        if user_options[:execution]
+          user_options[:execution].instance_exec(*value_proc_params, &value_proc)
+        else
+          value_proc.call(*value_proc_params)
+        end
+      end
+
+      def resolve_default_value(default_resolver)
+        if default_resolver.respond_to?(:call)
+          default_resolver.call
+        elsif default_resolver.respond_to?(:dup)
+          default_resolver.dup
+        else
+          default_resolver
         end
+      end
+
+      def filter_internal(value, user_options)
+        value
+      end
+
+      def value_callback(user_options)
+        resolve_value(nil, user_options, options[:value], [user_options[:object_value], user_options[:user_data]])
+      end
+
+      def before_callback(value, user_options)
+        resolve_value(value, user_options, options[:before], [value, user_options[:object_value], user_options[:user_data]])
+      end
+
+      def after_callback(value, user_options)
+        resolve_value(value, user_options, options[:after], [value, user_options[:object_value], user_options[:user_data]])
+      end
     end
   end
 end

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,69 +1,91 @@
 # 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:, options: {}, locked_options: {})
+        raise ArgumentError, 'properties 必须是 Properties 实例' unless properties.is_a?(Properties)
 
-      def initialize(properties: nil, options: {}, locked_options: {}, schema_name_resolver: proc { nil })
         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)
+        raise UnsupportedError, 'dup 不应该再执行了'
+
         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.merge(locked_options) if locked_options
         user_options = USER_OPTIONS_CHECKER.check(user_options)
-
-        object_value = super(object_value, user_options)
-
-        return nil if object_value.nil?
-        @properties.filter(object_value, user_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 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(stage: nil, **user_options)
-        locked_scopes = (locked_options || {})[:scope] || []
+      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(stage: stage, locked_scopes: locked_scopes, **user_options)
+        properties, required_keys = @properties.to_swagger_doc(**user_options)
         schema[:properties] = properties unless properties.empty?
         schema[:required] = required_keys unless required_keys.empty?
         schema
@@ -76,6 +98,22 @@ module Meta
       def locked_exclude
         locked_options && locked_options[:exclude]
       end
+
+      private
+
+      def filter_internal(object_value, user_options)
+        @properties.filter(object_value, user_options)
+      end
+
+      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
+          else
+            locked_value
+          end
+        end
+      end
     end
   end
 end

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

@@ -5,85 +5,33 @@ require 'forwardable'
 module Meta
   module JsonSchema
     class Properties
-      class StagingProperty
-        def initialize(param:, render:, none:)
-          @param_stage = param
-          @render_stage = render
-          @none_stage = none
-        end
-
-        def stage(stage = nil)
-          case stage
-          when :param
-            @param_stage
-          when :render
-            @render_stage
-          else
-            @none_stage
-          end
-        end
-
-        def stage?(stage)
-          stage(stage) != nil
-        end
-
-        def schema(stage = nil)
-          stage(stage).schema
-        end
-
-        def self.build(options, build_schema)
-          param_opts, render_opts, common_opts = SchemaOptions.divide_to_param_and_render(options)
-
-          StagingProperty.new(
-            param: options[:param] === false ? nil : ScopingProperty.build(param_opts, build_schema),
-            render: options[:render] === false ? nil : ScopingProperty.build(render_opts, build_schema),
-            none: ScopingProperty.build(common_opts, build_schema)
-          )
-        end
-      end
-
-      class ScopingProperty
-        attr_reader :scope, :schema
-
-        def initialize(scope: :all, schema:)
-          scope = :all if scope.nil?
-          scope = [scope] unless scope.is_a?(Array) || scope == :all
-          if scope.is_a?(Array) && scope.any? { |s| s.is_a?(Integer) }
-            raise ArgumentError, 'scope 选项内不可传递数字'
-          end
-          @scope = scope
-
-          @schema = schema
-        end
-
-        def self.build(options, build_schema)
-          options = options.dup
-          scope = options.delete(:scope)
-          schema = build_schema.call(options)
-          ScopingProperty.new(scope: scope, schema: schema)
-        end
-      end
-
       extend Forwardable
 
       def initialize(properties)
         @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 的属性都会被过滤
         user_scope = user_options[:scope] || [0]
         exclude = user_options.delete(:exclude) # 这里删除 exclude 选项，不要传递给下一层
         properties = filter_by(stage: stage, user_scope: user_scope)
-        filtered_properties = properties.filter do |name, property|
+        filtered_properties = properties.filter do |name, property_schema|
           # 通过 discard_missing 过滤
           next false if user_options[:discard_missing] && !object_value.key?(name.to_s)
 
           # 通过 locked_exclude 选项过滤
           next false if exclude && exclude.include?(name)
 
+          # 通过 if 选项过滤
+          next false unless property_schema.if?(user_options)
+
           # 默认返回 true
           next true
         end
@@ -91,12 +39,14 @@ module Meta
         # 第二步，递归过滤每一个属性
         object = {}
         errors = {}
+        cause = nil
         filtered_properties.each do |name, property_schema|
           value = resolve_property_value(object_value, name, property_schema)
 
           begin
             object[name] = property_schema.filter(value, **user_options, object_value: object_value)
           rescue JsonSchema::ValidationErrors => e
+            cause = e.cause || e if cause.nil? # 将第一次出现的错误作为 cause
             errors.merge! e.prepend_root(name).errors
           end
         end.to_h
@@ -108,54 +58,55 @@ module Meta
 
         if errors.empty?
           object
+        elsif cause
+          begin
+            raise cause
+          rescue
+            raise JsonSchema::ValidationErrors.new(errors)
+          end
         else
           raise JsonSchema::ValidationErrors.new(errors)
         end
       end
 
-      def to_swagger_doc(locked_scopes:, stage:, **user_options)
+      # 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)
         required_keys = properties.filter do |key, property_schema|
           property_schema.options[:required]
         end.keys
         properties = properties.transform_values do |property_schema |
-          property_schema.to_schema_doc(stage: stage, **user_options)
+          property_schema.to_schema_doc(stage: stage, scope: scope, **user_options)
         end
         [properties, required_keys]
       end
 
       # 程序中有些地方用到了这三个方法
-      def_delegators :@properties, :empty?, :key?, :[]
+      def_delegators :@properties, :empty?, :key?, :[], :each
 
       def merge(properties)
         self.class.new(@properties.merge(properties.instance_eval { @properties }))
       end
 
       def self.build_property(*args)
-        StagingProperty.build(*args)
+        StagingSchema.build_from_options(*args)
       end
 
       private
 
       def filter_by(stage:, user_scope: false)
-        properties = @properties.filter do |name, property|
-          # 通过 stage 过滤。
-          next false unless property.stage?(stage)
-          property = property.stage(stage)
-
-          # 通过 user_scope 过滤
-          next true if property.scope == :all
-          (user_scope - property.scope).empty? # user_scope 应被消耗殆尽
-        end
-        properties.transform_values do |property|
-          property.stage(stage).schema
+        @properties.transform_values do |property|
+          property.find_schema(stage: stage, scope: user_scope)
+        end.filter do |name, schema|
+          schema.filter?
         end
       end
 
       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,58 @@ 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 ||= {}
+
+        schema_name = object_schema.properties.schema_name(stage)
+        return defined_scopes_mapping[schema_name] if defined_scopes_mapping.key?(schema_name)
+
+        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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative '../support/scope_matcher'
+
+module Meta
+  module JsonSchema
+    class ScopingSchema < BaseSchema
+      attr_reader :scope_matcher, :schema
+
+      def initialize(scope_matcher_options: , schema:)
+        @scope_matcher = ScopeMatcher.new(scope_matcher_options)
+        @schema = schema
+      end
+
+      def scoped(user_scopes)
+        @scope_matcher.match?(user_scopes) ? schema : unsupported_schema(user_scopes)
+      end
+
+      def defined_scopes(**kwargs)
+        scope_matcher.defined_scopes
+      end
+
+      private
+
+      def unsupported_schema(user_scopes)
+        UnsupportedSchema.new(:scope, user_scopes)
+      end
+
+      def self.build_from_options(options, build_schema)
+        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
+      end
+    end
+  end
+end