meta-api 0.0.6 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4385e82bdaec80e15adc4b62b1259f30125720452e579d84a45c79471c2d9cb
-  data.tar.gz: f3b9baa683d4a757eabbcc9c13e86f133741f941f75c92bf8e28999d17f29653
+  metadata.gz: c114ab0d95b902ecefcd5e720f0c38fbcc420b2839194842c2974d2d073505fd
+  data.tar.gz: 994b7e975626f9907467edfe4283875aa113957edc860b74ed1b29e27560f196
 SHA512:
-  metadata.gz: 29e7fa33cae933c185cad5ea6bc5e0a9e460f549b5ea8bd12a6217b93e473d61a9cd5eaba2f803c28a5a55710a3668db80c42ad656b526cfb8604e50cdb42721
-  data.tar.gz: c7774b6feb64e9646017a7034082ab81b9fcf9a3928450edd725192671126a472941da314f64eb5c798a253eec6c82a99ff0701db6eacbda31cff42b6a605de0
+  metadata.gz: 6b62b24879f309c6cc67e45bc9bfd250b47ec8ad6c25f5fe1e9f5098b970ff8466f239b8799b4e653ebdc5568cbbb87fdd7c086703a99ef8525945ce24c44617
+  data.tar.gz: edec25f4ea37588611af7dceca41a443c5cb6d83586096f51f9f27ce75fdf290ec7085e4f27bf87043779e1ed289f7cbaa0a7e9568839e2ed206eef1d7d4f4b7

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 更新日志
 
+## 0.0.7（2023 年 7 月 14 日）
+
+1. 定义 parameters 宏时能够自动识别 `path` 参数。
+2. 定义 params 宏时能够自动识别 `GET` 路由，此时参数的 `in` 默认为 `query`.
+3. JsonSchema: `default:` 选项可以是一个块。
+4. 有且只有一个 `status` 宏定义时，不需要显示地设置 `response.status`.
+5. `Meta.config` 添加一个新的选析 `default_locked_scope`，借助它可以设置一个默认的 `locked_scope` 值。
+6. `JsonSchema` 的 `filter` 方法添加一个新的选项 `extra_properties:`，当设定值为 `:ignore` 时可以允许额外的属性。
+7. 添加新的选项 `config.json_schema_user_options`、`config.json_schema_param_stage_options`、`config.json_schema_render_stage_options`. 借助这三个选项可以对 `JsonSchema#filter` 方法的选项进行设置。同时废弃了 `render_type_conversion`、`render_validation` 等零散的选项。
+8. `meta` 宏的父级、子级的合并规则调整：parameters、params、responses 都有所合并。
+
 ## 0.0.6（2023 年 5 月 26 日）
 
 1. 添加了 Meta::Execution#abort_execution! 方法。

data/Gemfile.lock

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

data/README.md

@@ -17,7 +17,7 @@ $ git clone https://github.com/yetrun/web-frame-example.git
 在 Gemfile 中添加：
 
 ```ruby
-gem 'meta-api', '~> 0.0.5' # Meta 框架处于快速开发阶段，引入时应尽量固定版本
+gem 'meta-api', '~> 0.0.7' # Meta 框架处于快速开发阶段，引入时应尽量固定版本
 ```
 
 然后在 Ruby 代码中引用：

data/config/locales/zh-CN.yml

@@ -6,7 +6,7 @@ zh-CN:
     errors:
       required: "未提供"
       format: "格式不正确"
-      allowable: "不在允许的值范围内"
+      allowable: "不在允许的值范围内，允许的值包括 [%{allowable_values}]"
       type_convert:
         basic: "类型转化失败，期望得到一个 `%{target_type}` 类型，但值 `%{value}` 无法转化"
         array: "转化为数组类型时期望对象拥有 `to_a` 方法"

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

@@ -1064,7 +1064,8 @@ end
 
 ```ruby
 params do
-  param :age, default: 18
+  param :age, default: 18 # 通过值设定
+  param :name, default: -> { 'Jim' } # 通过块设定
 end
 ```
 
@@ -1451,15 +1452,62 @@ DemoApp.to_swagger_doc(
 
 ## 全局配置
 
-### 关闭渲染时验证
+### 定义默认的 `locked_scope`
 
-默认情况下渲染时也会执行验证，以保证渲染的数据有效性，尽快发现错误。这在开发环境有用，但在生产环境没有必要。可使用下面的代码关闭渲染时的验证：
+```ruby
+Meta.config.default_locked_scope = 'default'
+```
+
+当 `Meta::Entity` 被引用时，其没有被锁定 `scope`. 如果我们如上设定了默认的 `scope`，则
+
+```ruby
+param :user, ref: UserEntity
+```
+
+的效果等价于
+
+```ruby
+param :user, ref: UserEntity.lock_scope('default')
+```
+
+这样做对生成文档有帮助。因为我们没有锁定 `UserEntity`，则文档中它的所有属性都会被列出来，而在实际执行时却不能得到带有 `scope` 标记的字段，这样往往在造成文档和实际情况的不一致。
+
+### 定义 `JsonSchema#filter` 方法的 `user_options`
+
+```ruby
+Meta.config.json_schema_user_options = {...}
+Meta.config.json_schema_param_stage_options = {...}
+Meta.config.json_schema_render_stage_options = {...}
+```
+
+**示例一：关闭渲染时验证**
+
+渲染时不执行类型转换和数据验证：
+```ruby
+Meta.config.json_schema_render_stage_options = {
+  type_conversion: false,
+  render_validation: false
+}
+```
+
+**示例二：默认使用 `discard_missing: true` 方案**
 
 ```ruby
-Meta.config.render_type_conversion = false # 渲染时不执行类型转换
-Meta.config.render_validation = false      # 渲染时不执行数据验证
+Meta.config.json_schema_user_options = {
+  discard_missing: true
+}
 ```
 
+或仅在参数阶段使用 `discard_missing: true` 方案：
+
+```ruby
+Meta.config.json_schema_param_stage_options = {
+  discard_missing: true
+}
+```
+
+> 提示：可以传入一切 `JsonSchema#filter` 支持的选项，参考 [JsonSchema#filter 支持的选项](索引.md)。
+
 ## 特殊用法举例
 
 ### 路由中实体定义的特殊用法

data/docs//347/264/242/345/274/225.md

@@ -171,3 +171,13 @@ end
 ```
 
 面对这两种使用方式，有何使用上的建议呢？我的建议是，你习惯用哪种就用哪种。
+
+## `JsonSchema#filter` 方法的用户选项
+
+### `discard_missing:`
+
+规定是否忽略缺失的属性。所谓缺失的属性，是指在 `ObjectSchema` 实体宏中定义，但数据中不包含这个键值的属性。你可以将 `discard_missing: true` 视为 HTTP Patch 方法，`discard_missing: false` 视为 HTTP Put 方法。
+
+### `extra_properties:`
+
+规定多余的属性的处理办法。所谓多余的属性，是指未在 `ObjectSchema`  实体宏中定义，但数据中依然存在这个键值的属性。一般来讲我们允许前端传递一些多余的属性，但可能在内部测试时设定为更严格的条件。

data/examples/rails_app/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: /home/run/workspace/personal/web-frame
   specs:
-    meta-api (0.0.4)
+    meta-api (0.0.6)
 
 GEM
   remote: https://gems.ruby-china.com/

data/lib/meta/application/execution.rb

@@ -9,7 +9,7 @@ module Meta
 
     def initialize(request)
       @request = request
-      @response = Rack::Response.new
+      @response = Rack::Response.new([], 0) # 状态码初始为 0，代表一个未设置状态
       @parameters = {}
     end
 
@@ -75,11 +75,6 @@ module Meta
       self.parameters = parameters_meta.filter(request).freeze
     end
 
-    # parse_params 不再解析参数了，而只是设置 @params_schema，并清理父路由解析的变量
-    def parse_params(params_schema)
-      @params_schema = params_schema
-    end
-
     def parse_request_body(schema)
       @request_body_schema = schema
     end
@@ -99,7 +94,12 @@ module Meta
           options = {}
         end
 
-        new_hash = entity_schema.filter(hash, **options, execution: self, stage: :render, validation: ::Meta.config.render_validation, type_conversion: ::Meta.config.render_type_conversion)
+        new_hash = entity_schema.filter(hash,
+          **Meta.config.json_schema_user_options,
+          **Meta.config.json_schema_render_stage_options,
+          **options,
+          execution: self, stage: :render
+        )
         response.content_type = 'application/json' if response.content_type.nil?
         response.body = [JSON.generate(new_hash)]
       else
@@ -109,7 +109,12 @@ module Meta
         renders.each do |key, render_content|
           raise Errors::RenderingError, "渲染的键名 `#{key}` 不存在，请检查实体定义以确认是否有拼写错误" unless entity_schema.properties.key?(key)
           schema = entity_schema.properties[key].schema(:render)
-          final_value[key] = schema.filter(render_content[:value], **render_content[:options], execution: self, stage: :render)
+          final_value[key] = schema.filter(render_content[:value],
+            **Meta.config.json_schema_user_options,
+            **Meta.config.json_schema_render_stage_options,
+            **render_content[:options],
+            execution: self, stage: :render
+          )
         rescue JsonSchema::ValidationErrors => e
           # 错误信息再度绑定 key
           errors.merge! e.errors.transform_keys! { |k| k.empty? ? key : "#{key}.#{k}" }
@@ -148,13 +153,23 @@ module Meta
     end
 
     def parse_request_body_for_replacing
-      request_body_schema.filter(params(:raw), stage: :param)
+      request_body_schema.filter(
+        params(:raw),
+        **Meta.config.json_schema_user_options,
+        **Meta.config.json_schema_param_stage_options,
+        execution: self, stage: :param
+      )
     rescue JsonSchema::ValidationErrors => e
       raise Errors::ParameterInvalid.new(e.errors)
     end
 
     def parse_request_body_for_updating
-      request_body_schema.filter(params(:raw), stage: :param, discard_missing: true)
+      request_body_schema.filter(
+        params(:raw),
+        **Meta.config.json_schema_user_options,
+        **Meta.config.json_schema_param_stage_options,
+        execution: self, stage: :param, discard_missing: true
+      )
     rescue JsonSchema::ValidationErrors => e
       raise Errors::ParameterInvalid.new(e.errors)
     end

data/lib/meta/application/linked_action.rb

@@ -3,16 +3,14 @@
 # 洋葱圈模型的链式调用，需要结合 Meta::RouteDSL::AroundActionBuilder 才可以看到它奇效。
 
 module Meta
-  module RouteDSL
-    class LinkedAction
-      def initialize(current_proc, next_action)
-        @current_proc = current_proc
-        @next_action = next_action
-      end
+  class LinkedAction
+    def initialize(current_proc, next_action)
+      @current_proc = current_proc
+      @next_action = next_action
+    end
 
-      def execute(execution)
-        execution.instance_exec(@next_action, &@current_proc)
-      end
+    def execute(execution)
+      execution.instance_exec(@next_action, &@current_proc)
     end
   end
 end

data/lib/meta/application/metadata.rb

@@ -11,7 +11,7 @@ module Meta
       @tags = tags
       @parameters = parameters.is_a?(Parameters) ? parameters : Parameters.new(parameters)
       @request_body = request_body
-      @responses = responses || { 204 => nil }
+      @responses = responses || {} # || { 204 => nil }
     end
 
     def [](key)
@@ -54,8 +54,10 @@ module Meta
       operation_object.compact
     end
 
-    def self.new(meta = {})
-      meta.is_a?(Metadata) ? meta : super(**meta)
+    class << self
+      def new(meta = {})
+        meta.is_a?(Metadata) ? meta : super(**meta)
+      end
     end
   end
 end

data/lib/meta/application/parameters.rb

@@ -7,7 +7,7 @@ module Meta
     attr_reader :parameters
 
     def initialize(parameters)
-      @parameters = parameters
+      @parameters = parameters.dup
     end
 
     def filter(request)

data/lib/meta/application/route.rb

@@ -10,6 +10,7 @@ module Meta
 
     attr_reader :path, :method, :meta, :action
 
+    # path 是局部 path，不包含由父级定义的前缀
     def initialize(path: '', method: :all, meta: {}, action: nil)
       @path = Utils::Path.normalize_path(path)
       @method = method
@@ -25,9 +26,10 @@ module Meta
 
       action.execute(execution) if action
 
+      set_status(execution)
       render_entity(execution) if @meta[:responses]
     rescue Execution::Abort
-      nil
+      execution.response.status = 200 if execution.response.status == 0
     end
 
     def match?(execution, remaining_path)
@@ -42,14 +44,24 @@ module Meta
 
     private
 
+    def set_status(execution)
+      response_definitions = @meta[:responses]
+      response = execution.response
+      if response.status == 0
+        response.status = (response_definitions&.length > 0) ? response_definitions.keys[0] : 200
+      end
+    end
+
     def render_entity(execution)
-      responses = @meta[:responses]
-      status = execution.response.status
-      codes = responses.keys
-      return unless codes.include?(status)
+      response_definitions = @meta[:responses]
+      return if response_definitions.empty? # 未设定 status 宏时不需要执行 render_entity 方法
+
+      # 查找 entity schema
+      entity_schema = response_definitions[execution.response.status]
+      return if entity_schema.nil?
 
-      entity_schema = responses[status]
-      execution.render_entity(entity_schema) if entity_schema
+      # 执行面向 schema 的渲染
+      execution.render_entity(entity_schema)
     end
   end
 end

data/lib/meta/config.rb

@@ -2,11 +2,16 @@
 
 module Meta
   class Config
-    attr_accessor :render_validation, :render_type_conversion
+    attr_accessor :default_locked_scope,
+                  :json_schema_user_options,
+                  :json_schema_param_stage_options,
+                  :json_schema_render_stage_options
 
     def initialize
-      @render_type_conversion = true
-      @render_validation = true
+      @default_locked_scope = nil
+      @json_schema_user_options = {}
+      @json_schema_param_stage_options = {}
+      @json_schema_render_stage_options = {}
     end
   end
 

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

@@ -12,7 +12,13 @@ module Meta
         SCHEMA_BUILDER_OPTIONS = Utils::KeywordArgs::Builder.build do
           permit_extras true
 
-          key :ref, alias_names: [:using]
+          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
+          }
           key :dynamic_ref, alias_names: [:dynamic_using], normalizer: ->(value) { value.is_a?(Proc) ? { resolve: value } : value }
         end
         def build(options = {}, &block)

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

@@ -25,14 +25,16 @@ module Meta
         options = OPTIONS_CHECKER.check(options)
         raise '不允许 BaseSchema 直接接受 array 类型，必须通过继承使用 ArraySchema' if options[:type] == 'array' && self.class == BaseSchema
 
-        @options = SchemaOptions.normalize(options)
+        @options = SchemaOptions.normalize(options).freeze
       end
 
       USER_OPTIONS_CHECKER = Utils::KeywordArgs::Builder.build do
-        key :stage, :execution, :object_value, :type_conversion, :validation, :user_data
+        key :execution, :object_value, :type_conversion, :validation, :user_data
+        key :stage, validator: ->(value) { raise ArgumentError, "stage 只能取值为 :param 或 :render" unless [:param, :render].include?(value) }
 
-        # 以下三个是 ObjectSchema 需要的选项
-        key :discard_missing, :exclude, :scope
+        # 以下是 ObjectSchema 需要的选项
+        # extra_properties 只能取值为 :ignore、:raise_error
+        key :discard_missing, :extra_properties, :exclude, :scope
       end
 
       def filter(value, user_options = {})
@@ -40,7 +42,7 @@ module Meta
 
         value = resolve_value(user_options) if options[:value]
         value = JsonSchema::Presenters.present(options[:presenter], value) if options[:presenter]
-        value = options[:default] if value.nil? && options.key?(:default)
+        value = resolve_default_value(options[:default]) if value.nil? && options.key?(:default)
         value = options[:convert].call(value) if options[:convert]
 
         # 第一步，转化值。
@@ -110,6 +112,16 @@ module Meta
             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
+        end
     end
   end
 end

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

@@ -48,7 +48,7 @@ module Meta
       end
 
       # 合并其他的属性，并返回一个新的 ObjectSchema
-      def merge(properties)
+      def merge_other_properties(properties)
         ObjectSchema.new(properties: self.properties.merge(properties))
       end
 

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

@@ -92,7 +92,7 @@ module Meta
         object = {}
         errors = {}
         filtered_properties.each do |name, property_schema|
-          value = resolve_property_value(object_value, name, property_schema, stage)
+          value = resolve_property_value(object_value, name, property_schema)
 
           begin
             object[name] = property_schema.filter(value, **user_options, object_value: object_value)
@@ -101,6 +101,11 @@ module Meta
           end
         end.to_h
 
+        # 第三步，检测是否有剩余的属性
+        if user_options[:extra_properties] == :raise_error && !(object_value.keys.map(&:to_sym) - properties.keys).empty?
+          raise JsonSchema::ValidationError, '遇到多余的属性'
+        end
+
         if errors.empty?
           object
         else
@@ -122,6 +127,10 @@ module Meta
       # 程序中有些地方用到了这三个方法
       def_delegators :@properties, :empty?, :key?, :[]
 
+      def merge(properties)
+        self.class.new(@properties.merge(properties.instance_eval { @properties }))
+      end
+
       def self.build_property(*args)
         StagingProperty.build(*args)
       end
@@ -143,7 +152,7 @@ module Meta
         end
       end
 
-      def resolve_property_value(object_value, name, property_schema, stage)
+      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)

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

@@ -28,7 +28,7 @@ module Meta
         },
         allowable: proc { |value, allowable_values|
           next if value.nil?
-          raise JsonSchema::ValidationError, I18n.t(:'json_schema.errors.allowable') unless allowable_values.include?(value)
+          raise JsonSchema::ValidationError, I18n.t(:'json_schema.errors.allowable', allowable_values: allowable_values) unless allowable_values.include?(value)
         }
       }
 

data/lib/meta/route_dsl/application_builder.rb

@@ -2,39 +2,36 @@
 
 require_relative 'route_builder'
 require_relative 'meta_builder'
+require_relative '../utils/route_dsl_builders'
 
 module Meta
   module RouteDSL
     class ApplicationBuilder
       include MetaBuilder::Delegator
 
-      def initialize(prefix = nil, &block)
-        @mod_prefix = prefix
+      def initialize(full_prefix = '/', &block)
+        @full_prefix = full_prefix
         @callbacks = []
         @error_guards = []
-        @meta_builder = MetaBuilder.new
+        @meta_builder = MetaBuilder.new(route_full_path: full_prefix)
         @mod_builders = []
         @shared_mods = []
 
         instance_exec &block if block_given?
       end
 
-      def build(parent_path: '', meta: {}, callbacks: [])
-        # 合并 meta 时不仅仅是覆盖，比如 parameters 参数需要合并
-        meta2 = (meta || {}).merge(@meta_builder.build)
-        if meta[:parameters] && meta2[:parameters]
-          meta2[:parameters] = meta[:parameters].merge(meta2[:parameters])
-        end
-
-        # 构建子模块
-        # 合并父级传递过来的 callbacks，将 before 和 around 放在前面，after 放在后面
-        parent_before = callbacks.filter { |cb| cb[:lifecycle] == :before || cb[:lifecycle] == :around }
-        parent_after = callbacks.filter { |cb| cb[:lifecycle] == :after }
-        callbacks = parent_before + @callbacks + parent_after
-        mods = @mod_builders.map { |builder| builder.build(parent_path: Utils::Path.join(parent_path, @mod_prefix), meta: meta2, callbacks: callbacks) }
+      # meta 和 callbacks 是父级传递过来的，需要合并到当前模块或子模块中。
+      #
+      # 为什么一定要动态传递 meta_options 参数？由于 OpenAPI 文档是面向路由的，parameters、request_body、
+      # responses 都存在于路由文档中，对应地 Metadata 对象最终只存在于路由文档中。因此，在构建过程中，需要将父
+      # 级传递过来的 Metadata 对象合并到当前模块，再层层合并到子模块。
+      def build(meta_options: {}, callbacks: [])
+        meta_options = Utils::RouteDSLBuilders.merge_meta_options(meta_options, @meta_builder.build)
+        callbacks = Utils::RouteDSLBuilders.merge_callbacks(callbacks, @callbacks)
+        mods = @mod_builders.map { |builder| builder.build(meta_options: meta_options, callbacks: callbacks) }
 
         Application.new(
-          prefix: @mod_prefix,
+          prefix: @full_prefix,
           mods: mods,
           shared_mods: @shared_mods,
           error_guards: @error_guards
@@ -48,7 +45,7 @@ module Meta
 
       # 定义路由块
       def route(path, method = nil, &block)
-        route_builder = RouteDSL::RouteBuilder.new(path, method, &block)
+        route_builder = RouteBuilder.new(path, method, parent_path: @full_prefix, &block)
         @mod_builders << route_builder
         route_builder
       end
@@ -108,13 +105,9 @@ module Meta
           @meta = meta
         end
 
-        def build(parent_path: '', meta: {}, **kwargs)
-          # 合并 meta 时不仅仅是覆盖，比如 parameters 参数需要合并
-          meta2 = (meta || {}).merge(@meta)
-          if meta[:parameters] && meta2[:parameters]
-            meta2[:parameters] = meta[:parameters].merge(meta2[:parameters])
-          end
-          @builder.build(parent_path: parent_path, meta: meta2, **kwargs)
+        def build(meta_options: {}, **kwargs)
+          meta_options = Utils::RouteDSLBuilders.merge_meta_options(meta_options, @meta)
+          @builder.build(meta_options: meta_options, **kwargs)
         end
       end
     end

data/lib/meta/route_dsl/around_action_builder.rb

@@ -45,35 +45,45 @@ module Meta
         end
       end
 
-      # 使用 before、after、around 系列和当前 action 共同构建洋葱圈模型。
-      # Note: 该方法可能被废弃!
-      #
-      # 构建成功后，执行顺序是：
-      #
-      # - before 序列
-      # - around 序列的前半部分
-      # - action
-      # - around 序列的后半部分
-      # - after 序列
-      #
-      def self.build(before: [], after: [], around: [], action: nil)
-        builder = AroundActionBuilder.new
+      class << self
+        # 使用 before、after、around 系列和当前 action 共同构建洋葱圈模型。
+        # Note: 该方法已被废弃!
+        #
+        # 构建成功后，执行顺序是：
+        #
+        # - before 序列
+        # - around 序列的前半部分
+        # - action
+        # - around 序列的后半部分
+        # - after 序列
+        #
+        def build(before: [], after: [], around: [], action: nil)
+          builder = AroundActionBuilder.new
 
-        # 首先构建 before 序列，保证它最先执行
-        builder.around do |next_action|
-          before.each { |p| self.instance_exec(&p) }
-          next_action.execute(self)
-        end unless before.empty?
-        # 然后构建 after 序列，保证它最后执行
-        builder.around do |next_action|
-          next_action.execute(self)
-          after.each { |p| self.instance_exec(&p) }
-        end unless after.empty?
-        # 接着应用洋葱圈模型，依次构建 around 序列、action
-        around.each { |p| builder.around(&p) }
-        builder.around { self.instance_exec(&action) } unless action.nil?
+          # 首先构建 before 序列，保证它最先执行
+          builder.around do |next_action|
+            before.each { |p| self.instance_exec(&p) }
+            next_action.execute(self)
+          end unless before.empty?
+          # 然后构建 after 序列，保证它最后执行
+          builder.around do |next_action|
+            next_action.execute(self)
+            after.each { |p| self.instance_exec(&p) }
+          end unless after.empty?
+          # 接着应用洋葱圈模型，依次构建 around 序列、action
+          around.each { |p| builder.around(&p) }
+          builder.around { self.instance_exec(&action) } unless action.nil?
 
-        builder.build
+          builder.build
+        end
+
+        def build_from_callbacks(callbacks: [])
+          around_action_builder = AroundActionBuilder.new
+          callbacks.each do |cb|
+            around_action_builder.send(cb[:lifecycle], &cb[:proc]) if cb[:proc]
+          end
+          around_action_builder.build
+        end
       end
     end
   end

data/lib/meta/route_dsl/meta_builder.rb

@@ -6,32 +6,39 @@ require_relative 'uniformed_params_builder'
 module Meta
   module RouteDSL
     class MetaBuilder
-      def initialize(&block)
+      def initialize(route_full_path:, route_method: :all, &block)
+        @route_full_path = route_full_path
+        @method = route_method
         @meta = {}
+        @parameters_builder = ParametersBuilder.new(route_full_path: route_full_path, route_method: route_method) # 默认给一个空的参数构建器，它只会处理 path 参数
 
         instance_exec &block if block_given?
       end
 
       def build
-        @meta
+        meta = @meta
+        if @meta[:parameters].nil? && @route_full_path =~ /[:*].+/
+          meta[:parameters] = ParametersBuilder.new(route_full_path: @route_full_path, route_method: @method).build
+        end
+        meta
       end
 
       def parameters(&block)
-        @meta[:parameters] = ParametersBuilder.new(&block).build
+        @meta[:parameters] = ParametersBuilder.new(route_full_path: @route_full_path, route_method: @method, &block).build
       end
 
       def request_body(options = {}, &block)
-        @meta[:request_body] = JsonSchema::SchemaBuilderTool.build(options, &block)
+        @meta[:request_body] = JsonSchema::SchemaBuilderTool.build(options, &block).to_schema
       end
 
       # params 宏是一个遗留的宏，它在一个宏定义块内同时定义 parameters 和 request_body
       def params(&block)
-        @meta[:parameters], @meta[:request_body] = UniformedParamsBuilder.new(&block).build
+        @meta[:parameters], @meta[:request_body] = UniformedParamsBuilder.new(route_full_path: @route_full_path, route_method: @method, &block).build
       end
 
-      def status(code, *other_codes, &block)
+      def status(code, *other_codes, **options, &block)
         codes = [code, *other_codes]
-        entity_schema = JsonSchema::SchemaBuilderTool.build(&block)
+        entity_schema = JsonSchema::SchemaBuilderTool.build(options, &block)
         @meta[:responses] = @meta[:responses] || {}
         codes.each { |code| @meta[:responses][code] = entity_schema }
       end
@@ -47,8 +54,8 @@ module Meta
       module Delegator
         method_names = MetaBuilder.public_instance_methods(false) - ['build']
         method_names.each do |method_name|
-          define_method(method_name) do |*args, &block|
-            @meta_builder.send(method_name, *args, &block) and self
+          define_method(method_name) do |*args, **kwargs, &block|
+            @meta_builder.send(method_name, *args, **kwargs, &block) and self
           end
         end
       end

data/lib/meta/route_dsl/parameters_builder.rb

@@ -1,24 +1,47 @@
 # frozen_string_literal: true
+
 require_relative '../application/parameters'
+require_relative '../utils/kwargs/checker'
 
 module Meta
   module RouteDSL
     class ParametersBuilder
-      def initialize(&block)
-        @parameters = {}
+      def initialize(route_full_path:, route_method:, &block)
+        @route_full_path = route_full_path || ''
+        @route_method = route_method
+        @parameter_options = {}
 
         instance_exec &block if block_given?
       end
 
-      def param(name, options)
+      def param(name, options = {})
+        # 修正 path 参数的选项
         options = options.dup
-        op_in = options.delete(:in) || 'query'
+        if path_param_names.include?(name) # path 参数
+          options = Utils::KeywordArgs::Checker.fix!(options, in: 'path', required: true)
+        else
+          options = Utils::KeywordArgs::Checker.merge_defaults!(options, in: 'query')
+        end
 
-        @parameters[name] = { in: op_in, schema: JsonSchema::BaseSchema.new(options) }
+        in_op = options.delete(:in)
+        @parameter_options[name] = { in: in_op, schema: JsonSchema::BaseSchema.new(options) }
       end
 
       def build
-        Parameters.new(@parameters)
+        # 补充未声明的 path 参数
+        (path_param_names - @parameter_options.keys).each do |name|
+          @parameter_options[name] = { in: 'path', schema: JsonSchema::BaseSchema.new(required: true) }
+        end
+
+        Parameters.new(@parameter_options)
+      end
+
+      private
+
+      def path_param_names
+        @_path_param_names ||= @route_full_path.split('/')
+                                               .filter { |part| part =~ /[:*].+/ }
+                                               .map { |part| part[1..-1].to_sym }
       end
     end
   end

data/lib/meta/route_dsl/route_builder.rb

@@ -3,7 +3,6 @@
 require 'json'
 require_relative '../entity'
 require_relative '../application/route'
-require_relative 'helpers'
 require_relative 'chain_builder'
 require_relative 'action_builder'
 require_relative 'meta_builder'
@@ -16,52 +15,27 @@ module Meta
 
       alias :if_status :status
 
-      def initialize(path = '', method = :all, &block)
+      # 这里的 path 局部的路径，也就是由 route 宏命令定义的路径
+      def initialize(path, method = :all, parent_path: '',&block)
+        route_full_path = Utils::Path.join(parent_path, path)
+
         @path = path || ''
         @method = method || :all
         @action_builder = nil
-        @meta_builder = MetaBuilder.new
+        @meta_builder = MetaBuilder.new(route_full_path: route_full_path, route_method: method)
 
         instance_exec &block if block_given?
       end
 
-      def build(parent_path: '', meta: {}, callbacks: {})
-        # 合并 meta 时不仅仅是覆盖，比如 parameters 参数需要合并
-        meta2 = (meta || {}).merge(@meta_builder.build)
-        if meta[:parameters] && meta2[:parameters]
-          meta2[:parameters] = meta[:parameters].merge(meta2[:parameters])
-        end
-
-        # 合并 parameters 参数
-        meta2[:parameters] ||= {}
-        path_params = Utils::Path.join(parent_path, @path).split('/')
-          .filter { |part| part =~ /[:*].+/ }
-          .map { |part| part[1..-1].to_sym }
-        path_params.each do |name|
-          unless meta2[:parameters].key?(name)
-            meta2[:parameters][name] = {
-              in: 'path',
-              schema: JsonSchema::BaseSchema.new(required: true)
-            }
-          end
-        end
-
-        # 构建洋葱圈模型的 LinkedAction
-        # 合并父级传递过来的 callbacks，将 before 和 around 放在前面，after 放在后面
-        parent_before = callbacks.filter { |cb| cb[:lifecycle] == :before || cb[:lifecycle] == :around }
-        parent_after = callbacks.filter { |cb| cb[:lifecycle] == :after }
-        callbacks = parent_before + [{ lifecycle: :before, proc: @action_builder&.build }] + parent_after
-        # 使用 AroundActionBuilder 构建洋葱圈模型
-        around_action_builder = AroundActionBuilder.new
-        callbacks.each do |cb|
-          around_action_builder.send(cb[:lifecycle], &cb[:proc]) if cb[:proc]
-        end
-        action = around_action_builder.build
+      def build(meta_options: {}, callbacks: {})
+        meta_options = Utils::RouteDSLBuilders.merge_meta_options(meta_options, @meta_builder.build)
+        callbacks = Utils::RouteDSLBuilders.merge_callbacks(callbacks, [{ lifecycle: :before, proc: @action_builder&.build }])
+        action = AroundActionBuilder.build_from_callbacks(callbacks: callbacks)
 
         Route.new(
           path: @path,
           method: @method,
-          meta: meta2,
+          meta: meta_options,
           action: action
         )
       end
@@ -81,14 +55,6 @@ module Meta
           self
         end
       end
-
-      private
-
-      def clone_meta(meta)
-        meta = meta.clone
-        meta[:responses] = meta[:responses].clone if meta[:responses]
-        meta
-      end
     end
   end
 end

data/lib/meta/route_dsl/uniformed_params_builder.rb

@@ -3,31 +3,49 @@
 module Meta
   module RouteDSL
     class UniformedParamsBuilder
-      def initialize(&block)
-        @parameters = {}
-        @request_body_builder = JsonSchema::ObjectSchemaBuilder.new
+      def initialize(route_full_path:, route_method:, &block)
+        @route_full_path = route_full_path
+        @route_method = route_method
+        @parameters_builder = ParametersBuilder.new(route_full_path: @route_full_path, route_method: @route_method)
+
+        @parameter_options = {}
 
         instance_exec &block if block_given?
       end
 
       def param(name, options = {}, &block)
-        options = options.dup
-        op_in = options.delete(:in) || 'body'
+        options = (options || {}).dup
+        in_op = options.delete(:in) || \
+          if path_param_names.include?(name)
+            'path'
+          elsif @route_method == :get
+            'query'
+          else
+            'body'
+          end
 
-        if op_in == 'body'
+        if in_op == 'body'
           property name, options, &block
         else
-          @parameters[name] = { in: op_in, schema: JsonSchema::BaseSchema.new(options) }
+          @parameters_builder.param name, options
         end
       end
 
       def property(name, options = {}, &block)
+        @request_body_builder ||= JsonSchema::ObjectSchemaBuilder.new
         @request_body_builder.property name, options, &block
       end
 
       def build
-        request_body = @request_body_builder.to_schema
-        [@parameters, request_body.properties.empty? ? nil : request_body]
+        [@parameters_builder.build, @request_body_builder&.to_schema]
+      end
+
+      private
+
+      def path_param_names
+        @_path_param_names ||= @route_full_path.split('/')
+                                               .filter { |part| part =~ /[:*].+/ }
+                                               .map { |part| part[1..-1].to_sym }
       end
     end
   end

data/lib/meta/swagger_doc.rb

@@ -47,13 +47,13 @@ module Meta
       #     ]
       def get_paths_and_routes!(application, prefix = '', store_routes = [])
         if (application.is_a?(Class) && application < Application) || application.is_a?(Application)
-          prefix = RouteDSL::Helpers.join_path(prefix, application.prefix)
+          prefix = Utils::Path.join(prefix, application.prefix)
           (application.routes + application.applications).each do |mod|
             get_paths_and_routes!(mod, prefix, store_routes)
           end
         elsif application.is_a?(Route)
           route = application
-          route_path = route.path == :all ? prefix : RouteDSL::Helpers.join_path(prefix, route.path)
+          route_path = route.path == :all ? prefix : Utils::Path.join(prefix, route.path)
           store_routes << [route_path, route] unless route.method == :all
         else
           raise "Param application must be a Application instance, Application module or a Route instance, but it got a `#{application}`"

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

@@ -55,10 +55,11 @@ module Meta
       class Argument
         DEFAULT_TRANSFORMER = ->(value) { value }
 
-        def initialize(name:, normalizer: DEFAULT_TRANSFORMER, alias_names: [])
+        def initialize(name:, normalizer: DEFAULT_TRANSFORMER, validator: nil, default: nil, alias_names: [])
           @key_name = name
           @consumer_names = [name] + alias_names
-          @normalizer = normalizer
+          @normalizer = default ? ->(value) { normalizer.call(value || default) } : normalizer
+          @validator = validator
         end
 
         def consume(final_args, args)
@@ -71,6 +72,7 @@ module Meta
         def consume_name(final_args, args, consumer_name)
           if args.key?(consumer_name)
             value = @normalizer.call(args.delete(consumer_name))
+            @validator.call(value) if @validator
             final_args[@key_name] = value
             true
           else

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Meta
+  module Utils
+    class KeywordArgs
+      module Checker
+        class << self
+          # 将 options 内的值修正为固定值，该方法会原地修改 options 选项。
+          # 如果 options 中的缺失相应的值，则使用 fixed_values 中的值补充；如果 options 中的值不等于 fixed_values 中对应的值，则抛出异常。
+          # 示例：
+          # （1）fix!({}, { a: 1, b: 2 }) # => { a: 1, b: 2 }
+          # （2）fix!({ a: 1 }, { a: 2 }) # raise error
+          def fix!(options, fixed_values)
+            fixed_values.each do |key, value|
+              if options.include?(key)
+                if options[key] != value
+                  raise ArgumentError, "关键字参数 #{key} 的值不正确，必须为 #{value}"
+                end
+              else
+                options[key] = value
+              end
+            end
+            options
+          end
+
+          def merge_defaults!(options, defaults)
+            defaults.each do |key, value|
+              options[key] = value unless options[key]
+            end
+            options
+          end
+        end
+      end
+    end
+  end
+end

data/lib/meta/utils/path.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
+#
 
 module Meta
   module Utils
     class Path
       class << self
+        # 规范化 path 结构，确保 path 以 '/' 开头，不以 '/' 结尾。
+        # 仅有一个例外，如果 path 为 nil 或空字符串，则返回空字符串 ''.
         def normalize_path(path)
           path = '/' unless path
           path = '/' + path unless path.start_with?('/')
@@ -11,8 +14,11 @@ module Meta
           path
         end
 
-        def join(p1, p2)
-          normalize_path(normalize_path(p1) + '/' + normalize_path(p2))
+        # 合并两个 path. 有且只有一个例外，如果 p1 或 p2 其中之一为 '/'，则返回另一个。
+        def join(*parts)
+          parts = parts.map { |p| (p || '').delete_prefix('/').delete_suffix('/') }
+          parts = parts.reject { |p| p.nil? || p.empty? }
+          '/' + parts.join('/')
         end
       end
     end

data/lib/meta/utils/route_dsl_builders.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Meta
+  module Utils
+    class RouteDSLBuilders
+      class << self
+        def merge_meta_options(options1, options2)
+          final_options = (options1 || {}).merge(options2 || {})
+          if options1[:parameters] && options2[:parameters]
+            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)
+          end
+          if options1[:responses] && options2[:responses]
+            final_options[:responses] = options1[:responses].merge(options2[:responses])
+          end
+          final_options
+        end
+
+        def merge_callbacks(parent_callbacks, current_callbacks)
+          # 合并父级传递过来的 callbacks，将 before 和 around 放在前面，after 放在后面
+          parent_before = parent_callbacks.filter { |cb| cb[:lifecycle] == :before || cb[:lifecycle] == :around }
+          parent_after = parent_callbacks.filter { |cb| cb[:lifecycle] == :after }
+          parent_before + current_callbacks + parent_after
+        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.6"
+  spec.version       = "0.0.7"
   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.6
+  version: 0.0.7
 platform: ruby
 authors:
 - yetrun
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-05-26 00:00:00.000000000 Z
+date: 2023-07-14 00:00:00.000000000 Z
 dependencies: []
 description: 一个 Web API 框架，该框架采用定义元信息的方式编写 API，并同步生成 API 文档
 email:
@@ -113,7 +113,6 @@ files:
 - lib/meta/route_dsl/application_builder.rb
 - lib/meta/route_dsl/around_action_builder.rb
 - lib/meta/route_dsl/chain_builder.rb
-- lib/meta/route_dsl/helpers.rb
 - lib/meta/route_dsl/meta_builder.rb
 - lib/meta/route_dsl/parameters_builder.rb
 - lib/meta/route_dsl/route_builder.rb
@@ -121,7 +120,9 @@ files:
 - lib/meta/swagger_doc.rb
 - lib/meta/utils/kwargs/builder.rb
 - lib/meta/utils/kwargs/check.rb
+- lib/meta/utils/kwargs/checker.rb
 - lib/meta/utils/path.rb
+- lib/meta/utils/route_dsl_builders.rb
 - meta-api.gemspec
 homepage: https://github.com/yetrun/web-frame
 licenses:
@@ -130,7 +131,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
@@ -145,8 +146,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.4.15
+signing_key: 
 specification_version: 4
 summary: 一个 Web API 框架
 test_files: []

data/lib/meta/route_dsl/helpers.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module Meta
-  module RouteDSL
-    module Helpers
-      class << self
-        def join_path(*parts)
-          parts = parts.map { |p| (p || '').delete_prefix('/').delete_suffix('/') }
-          parts = parts.reject { |p| p.nil? || p.empty? }
-          '/' + parts.join('/')
-        end
-      end
-    end
-  end
-end