meta-api 0.0.5 → 0.0.7

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.5"
+  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.5
+  version: 0.0.7
 platform: ruby
 authors:
 - yetrun
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-04-27 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:
@@ -145,7 +146,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.4.15
 signing_key: 
 specification_version: 4
 summary: 一个 Web API 框架

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