meta-api 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09b85e846db5773168de2e283df9b42ddb22cf410f3c4696cfbb65c091c6b24f'
-  data.tar.gz: 95ad752071f7601069da746240750301e286ea880749bb5a071e4f1192d838f3
+  metadata.gz: 7364c618306dc9d04e6e08784670157e64b57f3f90b1828a259ba713268bb281
+  data.tar.gz: 00d25192ac7e4b4c733f1aa0d44a2424290d2bc4e290ca99d810686b744ec102
 SHA512:
-  metadata.gz: 7053ba6b9eac44a5b59bd0429a615c00e2d561708fad5d68abd00c7bf7f4680dc3ef710f593dd9001a7c222f86e340f99886892eff0fc672938b223456795e85
-  data.tar.gz: e270051a232829e6c9fef9f21b8d181ba466b981860e0d34599cba50b633b324181b03982d040c2470066cc4491be01483ddb093b81d69e7c6ed2c9a69caaf6e
+  metadata.gz: 62eabc56bc4ef76f76cb131f5b901a32875e12b8905857529307dee1acd0a4a354e2822f622f9ef43939444e89e08933e025404050a4347a77fbf169f8a7fe9f
+  data.tar.gz: 6692c9733a12d3acccc18d1cf6227a084c926dfd69b4acaae872e553683b4e70ca85d1aca874d87c169be1c2a68ca51e62ede1c142ef070829f508b7c2820426

data/.gitignore

@@ -1,4 +1,5 @@
 .DS_Store
+*.gem
 /.idea
 /.ruby-version
 

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# 更新日志
+
+## V0.0.2（2023 年 3 月 8 日）
+
+1. 添加两个配置项，适合生产环境下使用，用以关闭渲染时的数据验证验证。
+2. 添加对多态实体的支持。

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    meta-api (0.0.1)
+    meta-api (0.0.2)
 
 GEM
   remote: https://gems.ruby-china.com/

data/README.md

@@ -9,7 +9,7 @@ Meta 框架是一个适用于 Web API 的后端框架，采用 Ruby 语言编写
 你可直接使用我的脚手架项目上手体验：
 
 ```bash
-$ git clone https://github.com/yetrun/web-frame-example
+$ git clone https://github.com/yetrun/web-frame-example.git
 ```
 
 ## 安装
@@ -17,7 +17,7 @@ $ git clone https://github.com/yetrun/web-frame-example
 在 Gemfile 中添加：
 
 ```ruby
-gem 'meta-api', git: 'https://github.com/yetrun/web-frame'
+gem 'meta-api', '~> 0.0.1' # Meta 框架处于快速开发阶段，引入时应尽量固定版本
 ```
 
 然后在 Ruby 代码中引用：
@@ -144,6 +144,10 @@ run NotesAPI
 - [教程](docs/教程.md)
 - [索引](docs/索引.md)
 
+## 支持
+
+加 QQ 群（489579810）可获得实时答疑。
+
 ## License
 
 LGPL-2.1

data/docs//346/225/231/347/250/213.md

@@ -1032,6 +1032,27 @@ action do
 end
 ```
 
+### 多态参数和返回值
+
+定义属性时可定义多态类型，`using` 选项可接受一个块，它根据值来返回指定的类型：
+
+```ruby
+property :target, using: ->(value) {
+  # 根据 value.target_type 值返回实体类型
+  # 例如，value.target_type == 'UserEntity'，将返回 UserEntity 类
+  value.target_type.constantize
+}
+```
+
+或者接受一个 Hash，这时可提供 `one_of` 选项为文档生成提供加成：
+
+```ruby
+property :animal, using: {
+  one_of: [CatEntity, DogEntity, PigEntity],
+  resolve: ->(value) { value.animal_type.constantize }
+}
+```
+
 ## 生成文档
 
 应用模块提供一个 `to_swagger_doc` 方法生成 Open API 规格文档，该文档可被 Swagger UI 或基于 Swagger UI 的引擎渲染。
@@ -1058,9 +1079,18 @@ DemoApp.to_swagger_doc(
 > 
 > 了解 [Swagger UI](https://swagger.io/tools/swagger-ui/).
 
-## 特殊用法举例
+## 全局配置
+
+### 关闭渲染时验证
+
+默认情况下渲染时也会执行验证，以保证渲染的数据有效性，尽快发现错误。这在开发环境有用，但在生产环境没有必要。可使用下面的代码关闭渲染时的验证：
 
-##
+```ruby
+Meta.config.render_type_conversion = false # 渲染时不执行类型转换
+Meta.config.render_validation = false      # 渲染时不执行数据验证
+```
+
+## 特殊用法举例
 
 ### 路由中实体定义的特殊用法
 

data/lib/meta/api.rb

@@ -1,3 +1,4 @@
+require_relative 'config'
 require_relative 'application'
 require_relative 'swagger_doc'
 require_relative 'load_i18n'

data/lib/meta/application/execution.rb

@@ -83,7 +83,7 @@ module Meta
       end.to_h.freeze
     end
 
-    # REVIEW: parse_params 不再解析参数了，而只是设置 @params_schema，并清理父路由解析的变量
+    # parse_params 不再解析参数了，而只是设置 @params_schema，并清理父路由解析的变量
     def parse_params(params_schema)
       @params_schema = params_schema
     end
@@ -107,7 +107,7 @@ module Meta
           options = {}
         end
 
-        new_hash = entity_schema.filter(hash, **options, execution: self, stage: :render)
+        new_hash = entity_schema.filter(hash, **options, execution: self, stage: :render, validation: ::Meta.config.render_validation, type_conversion: ::Meta.config.render_type_conversion)
         response.body = [JSON.generate(new_hash)]
       else
         # 渲染多键值结点

data/lib/meta/config.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Meta
+  class Config
+    attr_accessor :render_validation, :render_type_conversion
+
+    def initialize
+      @render_type_conversion = true
+      @render_validation = true
+    end
+  end
+
+  @config = Config.new
+  class << self
+    attr_reader :config
+  end
+end

data/lib/meta/entity.rb

@@ -4,7 +4,6 @@ require 'forwardable'
 require_relative 'errors'
 require_relative 'json_schema/schemas'
 
-# Meta::Entity 是 ObjectSchemaBuilder 的一个类封装，它不应有自己的逻辑
 module Meta
   class Entity
     class << self

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

@@ -42,21 +42,21 @@ module Meta
 
       def property(name, options = {}, &block)
         name = name.to_sym
+        # REVIEW: 为何要 dup，删掉试试
         options = options.dup
 
-        # 能且仅能 ObjectSchemaBuilder 内能使用 using 选项
-        block = options[:using] unless block_given?
-        if block.nil? || block.is_a?(Proc)
-          @properties[name] = SchemaBuilderTool.build(options, &block)
-        elsif block.respond_to?(:to_schema)
-          schema = block.to_schema
+        using = options[:using]
+        if using.respond_to?(:to_schema)
+          schema = using.to_schema
           if options[:type] == 'array'
             @properties[name] = ArraySchema.new(schema, options)
           else
             @properties[name] = schema.dup(options)
           end
+        elsif using.is_a?(Proc) || using.is_a?(Hash) || using.nil?
+          @properties[name] = SchemaBuilderTool.build(options, &block)
         else
-          raise "非法的参数。应传递代码块，或通过 using 选项传递 Proc、ObjectScope 或接受 `to_schema` 方法的对象。当前传递：#{block}"
+          raise "非法的 `using` 选项，应传递具有 `to_schema` 方法（如 Entity、Schema 等）或 Hash、Proc（动态生成 Schema）。当前传递：#{block}"
         end
       end
 

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

@@ -43,6 +43,22 @@ module Meta
       end
 
       def filter(value, user_options = {})
+        user_options = Utils::KeywordArgs.check(
+          args: user_options,
+          schema: {
+            stage: nil,
+            execution: nil,
+            object_value: nil,
+            type_conversion: true,
+            validation: true,
+
+            # 以下三个是 ObjectSchema 需要的选项
+            discard_missing: false,
+            exclude: [],
+            scope: []
+          }
+        )
+
         stage_options = options(user_options[:stage])
 
         value = resolve_value(user_options) if stage_options[:value]
@@ -50,9 +66,10 @@ module Meta
         value = stage_options[:default] if value.nil? && stage_options.key?(:default)
         value = stage_options[:convert].call(value) if stage_options[:convert]
 
-        # 这一步转换值。需要注意的是，对象也可能被转换，因为并没有深层次的结构被声明。
+        # 第一步，转化值。
+        # 需要注意的是，对象也可能被转换，因为并没有深层次的结构被声明。
         type = stage_options[:type]
-        unless type.nil? || value.nil?
+        unless user_options[:type_conversion] == false || type.nil? || value.nil?
           begin
             value = JsonSchema::TypeConverter.convert_value(value, type)
           rescue JsonSchema::TypeConvertError => e
@@ -60,7 +77,14 @@ module Meta
           end
         end
 
-        validate!(value, stage_options)
+        # 第二步，做校验。
+        validate!(value, stage_options) unless user_options[:validation] == false
+
+        # 第三步，如果使用了 using 块，需要进一步解析
+        if stage_options[:using] && stage_options[:using].is_a?(Hash)
+          schema = stage_options[:using][:resolve].call(value).to_schema
+          value = schema.filter(value, user_options)
+        end
 
         value
       end
@@ -89,6 +113,12 @@ module Meta
         schema[:type] = stage_options[:type] if stage_options[:type]
         schema[:description] = stage_options[:description] if stage_options[:description]
         schema[:enum] = stage_options[:allowable] if stage_options[:allowable]
+        if stage_options[:using] && stage_options[:using].is_a?(Hash)
+          using_options = stage_options[:using]
+          schema[:oneOf] = using_options[:one_of].map do |schema|
+            schema.to_schema.to_schema_doc(user_options)
+          end if using_options[:one_of]
+        end
 
         schema
       end

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../../utils/kwargs'
+
 module Meta
   module JsonSchema
     class ObjectSchema < BaseSchema
@@ -93,8 +95,12 @@ module Meta
       # > 则该 Schema 生成文档时会使用 $ref 格式。除非 to_ref 选项设置为 false.
       #
       def to_schema_doc(user_options)
+        Utils::KeywordArgs.check(
+          args: user_options,
+          schema: { stage: nil, scope: nil, to_ref: false, schemas: nil }
+        )
+
         stage = user_options[:stage]
-        # HACK: 标准化选项的工作进行得怎样？
         locked_scopes = (locked_options || {})[:scope] || []
         locked_scopes = [locked_scopes] unless locked_scope.nil? && locked_scopes.is_a?(Array)
         schema_name = @schema_name_resolver.call(stage, locked_scopes)

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

@@ -8,7 +8,7 @@ module Meta
         required: false
       }
       @allowable_options = (
-        %i[type description in value using default presenter convert scope items] +
+        %i[type description in value using default presenter convert scope items using] +
         @default_options.keys + 
         JsonSchema::Validators.keys
       ).uniq
@@ -35,6 +35,8 @@ module Meta
           # 只要 options 中设置为 nil 的选项没有明确的意义，则下行代码是永远有效的
           options = (@default_options.compact).merge(options.compact)
           options[:scope] = [options[:scope]] unless options[:scope].is_a?(Array)
+          # TODO: 更好的规范选项的方式，以及如何检查深层次嵌套下参数类型的错误
+          options[:using] = { resolve: options[:using] } if options[:using].is_a?(Proc)
           if options[:using]
             if options[:type].nil?
               options[:type] = 'object'

data/lib/meta/utils/kwargs.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# 运行时检查关键字参数。
+#
+# 在 Ruby 3 中，关键字参数有所变化。简单来说，关键字参数和 Hash 类型不再自动转化，并且一般情况下推荐使用关键字参数。
+# 但关键字参数还是有稍稍不足之处，比如在做一些复杂的关键字参数定义时。
+#
+# 这个文件编写了一个方法，帮助我们在运行时检查关键字参数。这样，我们就可以像下面这样笼统的方式定义参数，不必用明确的关
+# 键字参数名称。
+#
+#     def method_name(x, y, z, **kwargs); end
+#     def method_name(x, y, z, kwargs={}); end
+#
+# 使用示例：
+#
+#     # 返回 { x: 1, y: 2, z: 3 }
+#     Meta::Utils::KeywordArgs.check(args: { x: 1, y: 2 }, schema: [:x, :y, { z: 3 }])
+#
+#     # 返回 { x: 1, y: 2, z: 4 }
+#     Meta::Utils::KeywordArgs.check(args: { x: 1, y: 2, z: 4 }, schema: [:x, :y, { z: 3 }])
+#
+#     # Error: `x` is required
+#     Meta::Utils::KeywordArgs.check(args: { y: 2, z: 3 }, schema: [:x, :y, { z: 3 }])
+#
+#     # Error: `a` is not allowed
+#     Meta::Utils::KeywordArgs.check(args: { a: 1, y: 2, z: 3 }, schema: [:x, :y, { z: 3 }])
+
+module Meta
+  module Utils
+    class KeywordArgs
+      class << self
+        def check(args:, schema:)
+          schemas = build_schemas(schema)
+
+          # 不接受额外的关键字参数
+          extras = args.keys - schemas.keys
+          raise "不接受额外的关键字参数：#{extras.join(', ')}" unless extras.empty?
+
+          # 通过 schema 导出关键字参数
+          missing = []
+          result = schemas.map do |name, spec|
+            if args.include?(name)
+              [name, args[name]]
+            elsif spec.include?(:default)
+              [name, spec[:default]]
+            else
+              missing << name
+            end
+          end.to_h
+
+          # 检查以上导出过程中是否找到缺失的参数
+          if missing.empty?
+            result
+          else
+            raise "缺失必要的关键字参数：#{missing.join(', ')}"
+          end
+        end
+
+        private
+
+          def build_schemas(spec)
+            if spec.is_a?(Array)
+              build_schemas_from_array(spec)
+            elsif spec.is_a?(Hash)
+              build_schemas_from_hash(spec)
+            elsif spec.is_a?(Symbol)
+              build_schemas_from_symbol(spec)
+            else
+              raise "未知的参数类型：#{spec.class}"
+            end
+          end
+
+          def build_schemas_from_array(spec_array)
+            spec_array.inject({}) do |accumulated, val|
+              accumulated.merge!(build_schemas(val))
+            end
+          end
+
+          def build_schemas_from_hash(spec_hash)
+            spec_hash.transform_values do |val|
+              { default: val }
+            end
+          end
+
+          def build_schemas_from_symbol(spec_symbol)
+            { spec_symbol => {} }
+          end
+      end
+    end
+  end
+end

data/meta-api.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name          = "meta-api"
-  spec.version       = "0.0.1"
+  spec.version       = "0.0.2"
   spec.authors       = ["yetrun"]
   spec.email         = ["yetrun@foxmail.com"]
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: meta-api
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - yetrun
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-01-02 00:00:00.000000000 Z
+date: 2023-03-08 00:00:00.000000000 Z
 dependencies: []
 description: 一个 Web API 框架，该框架采用定义元信息的方式编写 API，并同步生成 API 文档
 email:
@@ -20,6 +20,7 @@ files:
 - ".autoenv.zsh"
 - ".gitignore"
 - ".rubocop.yml"
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
@@ -41,6 +42,7 @@ files:
 - lib/meta/application/meta.rb
 - lib/meta/application/path_matching_mod.rb
 - lib/meta/application/route.rb
+- lib/meta/config.rb
 - lib/meta/entity.rb
 - lib/meta/errors.rb
 - lib/meta/json_schema/builders/array_schema_builder.rb
@@ -65,6 +67,7 @@ files:
 - lib/meta/route_dsl/route_builder.rb
 - lib/meta/route_dsl/uniformed_params_builder.rb
 - lib/meta/swagger_doc.rb
+- lib/meta/utils/kwargs.rb
 - lib/meta/utils/path.rb
 - meta-api.gemspec
 homepage: https://github.com/yetrun/web-frame
@@ -74,7 +77,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/yetrun/web-frame
   source_code_uri: https://github.com/yetrun/web-frame.git
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -89,8 +92,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
-signing_key:
+rubygems_version: 3.3.7
+signing_key: 
 specification_version: 4
 summary: 一个 Web API 框架
 test_files: []