meta-api 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf3fb639df71a5353328e898711c9758c5e5fd3dd1760409ae823fbd0a7852e2
-  data.tar.gz: ea5dd728c3691fcf542d1085fd21d787d727c97b588652de3ffdd53b67512437
+  metadata.gz: f5f1c4106f4106c1a3e69249e35f4efc02d4ca5d5981d4e32442c380f4228556
+  data.tar.gz: 7dc942b0a36759a0953a255b18a7c6c6312159365e9b829b48f223d0d83cd685
 SHA512:
-  metadata.gz: 4a9f0a02d8091f77e7f9c2ea0ea67b86f1877327a7b75a7f4342fecd7f2822f9bde2ded59c20cb1c3227eb88a4b6b098c9438710a6a8eedcf4c8defb2f37c572
-  data.tar.gz: 2e7911858914bd1b34ff60007f48757f6afb1183c59d15d9e490fb5fe781244522d5500251dcbdbb02fc5f26a17d48ab82bbc2f6dd4368c2540f97bb351f6da3
+  metadata.gz: 275731f780c2e5eb3dcae314a5b7832504f053092eee8aa3eb1e8b85d7cce0f4fec33bf8f46626cb307d6c7c98e6ff0ee13bf100d6a4610099323d069968d7ae
+  data.tar.gz: f3f21b6e62503946e26471f9199809247d0ee3fafa13a2190e57aadb038b47cb19757ed08be4f2054e2b0151c2ed9f1cf4d737c007e133479395aa936d2a338b

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 更新日志
 
+## 0.1.1（2024 年 6 月 1 日）
+
+1. 添加 `Meta::Entity.with_common_options` 方法，用于更有效地组织字段。
+2. 临时性地添加 `Meta::Entity.merge` 方法，作为合并其他的实体的暂时性实现。
+3. scope 分为全局 scope 和局部 scope.
+
 ## 0.1.0（2023 年 8 月 5 日）
 
 1. 删除 `on:` 选项。

data/lib/meta/entity.rb

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

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

@@ -5,6 +5,8 @@ require_relative '../schemas/properties'
 module Meta
   module JsonSchema
     class ObjectSchemaBuilder
+      extend Forwardable
+
       module LockedMethodAlias
         # 我在这里说明一下 lock_scope 的逻辑。
         # 1. lock_scope 实际上是将 scope 传递到当前的 ObjectSchema 和它的子 Schema 中。
@@ -29,10 +31,49 @@ module Meta
         end
       end
 
+      class Locked
+        attr_reader :object_schema_builder, :locked_options
+
+        # locked_options 是用户传递的参数，这个参数会被合并到 object_schema_builder 的 locked_options 中。
+        def initialize(builder, scope: nil, discard_missing: nil, exclude: nil)
+          @object_schema_builder = builder
+          @locked_options = ObjectSchema::USER_OPTIONS_CHECKER.check({ scope: scope, discard_missing: discard_missing, exclude: exclude }.compact)
+        end
+
+        def to_schema
+          object_schema_builder.to_schema(locked_options)
+        end
+
+        def locked(options)
+          options = ObjectSchema::USER_OPTIONS_CHECKER.check(options)
+          options = ObjectSchema.merge_user_options(locked_options, options)
+          Locked.new(self.object_schema_builder, **options)
+        end
+        include LockedMethodAlias
+      end
+
+      class WithCommonOptions
+        attr_reader :object_schema_builder, :common_options
+
+        def initialize(builder, common_options, &)
+          @object_schema_builder = builder
+          @common_options = common_options
+
+          instance_exec(&) if block_given?
+        end
+
+        def property(name, options = {}, &block)
+          options = 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 = {}
 
@@ -47,10 +88,13 @@ module Meta
         instance_exec(&) if block_given?
       end
 
-      def schema_name(schema_base_name)
-        raise TypeError, "schema_base_name 必须是一个 String，当前是：#{schema_base_name.class}" unless schema_base_name.is_a?(String)
-
-        @schema_name = schema_base_name
+      def schema_name(schema_base_name = nil)
+        if schema_base_name
+          raise TypeError, "schema_base_name 必须是一个 String，当前是：#{schema_base_name.class}" unless schema_base_name.is_a?(String)
+          @schema_name = schema_base_name
+        else
+          @schema_name
+        end
       end
 
       def property(name, options = {}, &block)
@@ -66,12 +110,50 @@ module Meta
         instance_exec(&proc)
       end
 
+      def with_common_options(common_options, &block)
+        WithCommonOptions.new(self, common_options, &block)
+      end
+
+      def scope(scope, options = {}, &)
+        with_common_options(**options, scope: scope, &)
+      end
+
+      def params(options = {}, &block)
+        with_common_options(**options, render: false, &block)
+      end
+
+      def render(options = {}, &block)
+        with_common_options(**options, params: false, &block)
+      end
+
+      def merge(schema_builder)
+        schema_builder = schema_builder.schema_builder if schema_builder.respond_to?(:schema_builder)
+
+        @properties.merge!(schema_builder.properties)
+      end
+
       def to_schema(locked_options = nil)
         properties = @schema_name ? NamedProperties.new(@properties, @schema_name) : Properties.new(@properties)
         ObjectSchema.new(properties: properties, options: @options, locked_options: locked_options)
       end
 
       def locked(options)
+        defined_scopes_mapping = {}
+        # TODO: 将 properties 搞成 Properties 可以吗？
+        defined_scopes = properties.map do |key, property|
+          property.defined_scopes(stage: :param, defined_scopes_mapping: defined_scopes_mapping)
+        end.flatten.uniq
+
+        user_scopes = options[:scope] || []
+        user_scopes = [user_scopes] unless user_scopes.is_a?(Array)
+
+        # 判断 user_scopes 中提供的局部 scope 是否在 defined_scopes 中
+        local_user_scopes = user_scopes.reject { |scope| scope.start_with?('$') }
+        if (local_user_scopes - defined_scopes).any?
+          extra_scopes = local_user_scopes - defined_scopes
+          raise ArgumentError, "scope #{extra_scopes.join(',')} 未在实体中定义"
+        end
+
         Locked.new(self, **options)
       end
       include LockedMethodAlias
@@ -85,27 +167,6 @@ module Meta
       def apply_object_scope?(options, block)
         (options[:type] == 'object' || block) && (options[:properties] || block)
       end
-
-      class Locked
-        attr_reader :object_schema_builder, :locked_options
-
-        # locked_options 是用户传递的参数，这个参数会被合并到 object_schema_builder 的 locked_options 中。
-        def initialize(builder, scope: nil, discard_missing: nil, exclude: nil)
-          @object_schema_builder = builder
-          @locked_options = ObjectSchema::USER_OPTIONS_CHECKER.check({ scope: scope, discard_missing: discard_missing, exclude: exclude }.compact)
-        end
-
-        def to_schema
-          object_schema_builder.to_schema(locked_options)
-        end
-
-        def locked(options)
-          options = ObjectSchema::USER_OPTIONS_CHECKER.check(options)
-          options = ObjectSchema.merge_user_options(locked_options, options)
-          Locked.new(self.object_schema_builder, **options)
-        end
-        include LockedMethodAlias
-      end
     end
   end
-end
+end

data/lib/meta/json_schema/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,19 +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
 

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

@@ -42,17 +42,6 @@ module Meta
         @locked_options = USER_OPTIONS_CHECKER.check(locked_options || {})
       end
 
-      # 复制一个新的 ObjectSchema，只有 options 不同
-      def dup(options)
-        raise UnsupportedError, 'dup 不应该再执行了'
-
-        self.class.new(
-          properties: properties,
-          options: options,
-          locked_options: locked_options,
-        )
-      end
-
       def filter(object_value, user_options = {})
         # 合并 user_options
         user_options = USER_OPTIONS_CHECKER.check(user_options)
@@ -64,6 +53,10 @@ module Meta
         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, user_scopes, defined_scopes)
         raise ArgumentError, 'stage 不能为 nil' if stage.nil?
 

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

@@ -30,7 +30,7 @@ module Meta
           next false if exclude && exclude.include?(name)
 
           # 通过 if 选项过滤
-          next false unless property_schema.if?(user_options)
+          next false unless property_schema.if?(object_value, user_options[:execution])
 
           # 默认返回 true
           next true
@@ -44,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
@@ -69,6 +75,12 @@ 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

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

@@ -40,8 +40,11 @@ module Meta
       def defined_scopes(stage:, defined_scopes_mapping:)
         defined_scopes_mapping ||= {}
 
-        schema_name = object_schema.properties.schema_name(stage)
-        return defined_scopes_mapping[schema_name] if defined_scopes_mapping.key?(schema_name)
+        if object_schema.properties.respond_to?(:schema_name)
+          # 只有命名实体才会被缓存
+          schema_name = object_schema.properties.schema_name(stage)
+          return defined_scopes_mapping[schema_name] if defined_scopes_mapping.key?(schema_name)
+        end
 
         defined_scopes_mapping[schema_name] = []
         defined_scopes = object_schema.properties.each.map do |name, property|

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

@@ -17,7 +17,9 @@ module Meta
       end
 
       def defined_scopes(**kwargs)
-        scope_matcher.defined_scopes
+        current = scope_matcher.defined_scopes
+        deep = schema.defined_scopes(**kwargs)
+        (current + deep).uniq
       end
 
       private

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/meta-api.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name          = "meta-api"
-  spec.version       = "0.1.0"
+  spec.version       = "0.1.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.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - yetrun
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-08-05 00:00:00.000000000 Z
+date: 2024-06-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hash_to_struct