meta-api 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b4cc662a6a580592192bcc29cd4367249d1bbba4678aee0f95d75d9ff01c219
-  data.tar.gz: 5bd5ed38531f286ba422a57b8da12aceb0c13a063be1d5c0895c5073abd5a868
+  metadata.gz: bc6f6c3dddfd1e683cae7147be60bd7ead57e46b097700fc1db4113d12f08965
+  data.tar.gz: 476caee521969debd84614433ab41be89fbe7d1e5b074f46a6c8df40ca2d2c43
 SHA512:
-  metadata.gz: b54219704c980114719f6cd9d53d1d77036a194eddd991610b88fe36f52ecf9e04abccfbfaad0d9acd527ba8edc294b333ca403752ff6a0a0f753c30e93d22cd
-  data.tar.gz: 564d6e0dfcae8a11aa59bc740e7fff4901326eff996171539156ae064ce205173c548f295e6d0d8cb085fd4de3b829c7141e5cff5aa343e658f8b2475b004d02
+  metadata.gz: 3e213a983004b7fed1d15c2e0b41c9746584d259af6f969c631669b7efbb63f5573ee67b61ca5cb95888738925ca525e2ae4045502a7998c57c96432c12e3fd7
+  data.tar.gz: b575cf5145a3693ceb14296178c25c1ab1f8bf23e2a7dac92e9cc131a82dd79649d101f066c716069a5cb99114c138842b7bde89734790f217095fd459bf8fb4

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 更新日志
 
+## 0.0.4（2023 年 4 月 18 日）
+
+1. `Application` 添加 `.around` 宏。
+2. `render` 时支持传递 `user_data` 选项，用作 value 解析的第二个参数。
+
 ## 0.0.3（2023 年 4 月 4 日）
 
 1. 添加两个新的选项 `ref:` 和 `dynamic_ref:`，以便后期取代 `using:`.

data/Gemfile.lock

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

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

@@ -118,7 +118,7 @@ class DemoApp < Meta::Application
 end
 ```
 
-### before/after 钩子
+### 钩子
 
 *（如果不涉及到钩子和异常拦截，嵌套路由将毫无意义。）*
 
@@ -142,6 +142,34 @@ class DemoApp < Meta::Application
 end
 ```
 
+同时还支持 `around` 钩子（*试验特性*）：
+
+```ruby
+class DemoApp < Meta::Application
+  before { puts 1 }
+  before { puts 2 }
+  around { |next_action|
+     puts 3
+     next_action.execute(self)
+     puts 5
+  }
+  after { puts 6 }
+  after { puts 7 }
+
+  get '/request' do
+    puts 4
+  end
+end
+```
+
+所有钩子的执行顺序是：
+
+1. 首先执行 `before` 钩子，按照定义的顺序执行。
+2. 然后执行 `around` 钩子的前半部分，按照定义的顺序执行。
+3. 然后执行路由方法。
+4. 然后执行 `around` 钩子的后半部分，按照定义的顺序执行。
+5. 最后执行 `after` 钩子，按照定义的顺序执行。
+
 ### 异常拦截
 
 在 `namespace` 中使用 `rescue_error` 拦截异常。

data/examples/rails_app/Gemfile.lock

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

data/lib/meta/application/linked_action.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# 洋葱圈模型的链式调用，需要结合 Meta::RouteDSL::AroundActionBuilder 才可以看到它奇效。
+
+module Meta
+  module RouteDSL
+    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
+    end
+  end
+end

data/lib/meta/application/route.rb

@@ -8,24 +8,23 @@ module Meta
   class Route
     include PathMatchingMod.new(path_method: :path, matching_mode: :full)
 
-    attr_reader :path, :method, :meta, :actions
+    attr_reader :path, :method, :meta, :action
 
-    def initialize(path: '', method: :all, meta: {}, actions: [])
+    def initialize(path: '', method: :all, meta: {}, action: nil)
       @path = Utils::Path.normalize_path(path)
       @method = method
       @meta = Metadata.new(meta)
-      @actions = actions
+      @action = action
     end
 
     def execute(execution, remaining_path)
       path_matching.merge_path_params(remaining_path, execution.request)
 
-      # 依次执行这个环境
       begin
         execution.parse_parameters(@meta[:parameters]) if @meta[:parameters]
         execution.parse_request_body(@meta[:request_body]) if @meta[:request_body]
 
-        actions.each { |b| execution.instance_eval(&b) }
+        action.execute(execution) if action
 
         render_entity(execution) if @meta[:responses]
       rescue Execution::Abort

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

@@ -5,15 +5,10 @@ module Meta
     class ArraySchemaBuilder
       def initialize(options, &block)
         options = options.dup
-        if options[:items]
-          items_options = options.delete(:items)
-        elsif options[:ref]
-          items_options = { ref: options.delete(:ref) }
-        elsif options[:dynamic_ref]
-          items_options = { dynamic_ref: options.delete(:dynamic_ref) }
-        else
-          items_options = {}
-        end
+        items_options = options.delete(:items) || {}
+        items_options[:ref] = options.delete(:ref) if options[:ref]
+        items_options[:dynamic_ref] = options.delete(:dynamic_ref) if options[:dynamic_ref]
+
         @items_schema = SchemaBuilderTool.build(items_options, &block)
         @base_options = options
       end

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

@@ -6,6 +6,12 @@ require_relative '../support/schema_options'
 module Meta
   module JsonSchema
     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
+      end
+
       # `options` 包含了转换器、验证器、文档、选项。
       #
       # 由于本对象可继承，基于不同的继承可分别表示基本类型、对象和数组，所以该属
@@ -16,11 +22,12 @@ module Meta
       attr_reader :options
 
       def initialize(options = {})
+        options = OPTIONS_CHECKER.check(options)
         @options = SchemaOptions.normalize(options)
       end
 
       USER_OPTIONS_CHECKER = Utils::KeywordArgs::Builder.build do
-        key :stage, :execution, :object_value, :type_conversion, :validation
+        key :stage, :execution, :object_value, :type_conversion, :validation, :user_data
 
         # 以下三个是 ObjectSchema 需要的选项
         key :discard_missing, :exclude, :scope
@@ -57,7 +64,13 @@ module Meta
 
       def resolve_value(user_options)
         value_proc = options[:value]
-        value_proc_params = (value_proc.lambda? && value_proc.arity == 0) ?  [] : [user_options[:object_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
 
         if user_options[:execution]
           user_options[:execution].instance_exec(*value_proc_params, &value_proc)

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

@@ -5,13 +5,6 @@ require_relative '../../utils/kwargs/builder'
 module Meta
   module JsonSchema
     module SchemaOptions
-      OPTIONS_CHECKER = Utils::KeywordArgs::Builder.build do
-        key :type, :items, :description, :presenter, :value, :format, :required, :default, :validate, :allowable, :properties, :convert
-        key :using, normalizer: ->(value) { value.is_a?(Proc) ? { resolve: value } : value }
-        key :param
-        key :render
-      end
-
       @default_options = {
         scope: [],
         required: false
@@ -34,8 +27,6 @@ module Meta
         end
 
         def normalize(options)
-          options = OPTIONS_CHECKER.check(options)
-
           # 只要 options 中设置为 nil 的选项没有明确的意义，则下行代码是永远有效的
           options = (@default_options.compact).merge(options.compact)
           if options[:using]

data/lib/meta/route_dsl/application_builder.rb

@@ -10,8 +10,7 @@ module Meta
 
       def initialize(prefix = nil, &block)
         @mod_prefix = prefix
-        @before_callbacks = []
-        @after_callbacks = []
+        @callbacks = { before: [], after: [], around: [] }
         @error_guards = []
         @meta_builder = MetaBuilder.new
         @mod_builders = []
@@ -20,7 +19,7 @@ module Meta
         instance_exec &block if block_given?
       end
 
-      def build(parent_path: '', meta: {}, before_callbacks: [], after_callbacks: [])
+      def build(parent_path: '', meta: {}, callbacks: {})
         # 合并 meta 时不仅仅是覆盖，比如 parameters 参数需要合并
         meta2 = (meta || {}).merge(@meta_builder.build)
         if meta[:parameters] && meta2[:parameters]
@@ -28,9 +27,12 @@ module Meta
         end
 
         # 构建子模块
-        before_callbacks += @before_callbacks
-        after_callbacks = @after_callbacks + after_callbacks
-        mods = @mod_builders.map { |builder| builder.build(parent_path: Utils::Path.join(parent_path, @mod_prefix), meta: meta2, before_callbacks: before_callbacks, after_callbacks: after_callbacks) }
+        callbacks = { # 合并父级传递过来的 callbacks
+          before: (callbacks[:before] || []) + @callbacks[:before],
+          around: (callbacks[:around] || []) + @callbacks[:around],
+          after: @callbacks[:after] + (callbacks[:after] || []),
+        }
+        mods = @mod_builders.map { |builder| builder.build(parent_path: Utils::Path.join(parent_path, @mod_prefix), meta: meta2, callbacks: callbacks) }
 
         Application.new(
           prefix: @mod_prefix,
@@ -64,11 +66,15 @@ module Meta
 
       # 定义模块内的公共逻辑
       def before(&block)
-        @before_callbacks << block
+        @callbacks[:before] << block
       end
 
       def after(&block)
-        @after_callbacks << block
+        @callbacks[:after] << block
+      end
+
+      def around(&block)
+        @callbacks[:around] << block
       end
 
       def rescue_error(error_class, &block)
@@ -94,13 +100,13 @@ module Meta
           @meta = meta
         end
 
-        def build(parent_path: '', meta: {}, before_callbacks: [], after_callbacks: [])
+        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, before_callbacks: before_callbacks, after_callbacks: after_callbacks)
+          @builder.build(parent_path: parent_path, meta: meta2, **kwargs)
         end
       end
     end

data/lib/meta/route_dsl/around_action_builder.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative '../application/linked_action'
+
+module Meta
+  module RouteDSL
+    class AroundActionBuilder
+      def initialize
+        @around = []
+      end
+
+      def around(&block)
+        @around << block
+      end
+
+      def build
+        # 从后向前构建
+        @around.reverse.reduce(nil) do |following, p|
+          LinkedAction.new(p, following)
+        end
+      end
+
+      # 使用 before、after、around 系列和当前 action 共同构建洋葱圈模型。
+      # 构建成功后，执行顺序是：
+      #
+      # - before 序列
+      # - around 序列的前半部分
+      # - action
+      # - around 序列的后半部分
+      # - after 序列
+      #
+      def self.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?
+
+        builder.build
+      end
+    end
+  end
+end

data/lib/meta/route_dsl/route_builder.rb

@@ -7,6 +7,7 @@ require_relative 'helpers'
 require_relative 'chain_builder'
 require_relative 'action_builder'
 require_relative 'meta_builder'
+require_relative 'around_action_builder'
 
 module Meta
   module RouteDSL
@@ -24,7 +25,7 @@ module Meta
         instance_exec &block if block_given?
       end
 
-      def build(parent_path: '', meta: {}, before_callbacks: [], after_callbacks: [])
+      def build(parent_path: '', meta: {}, callbacks: {})
         # 合并 meta 时不仅仅是覆盖，比如 parameters 参数需要合并
         meta2 = (meta || {}).merge(@meta_builder.build)
         if meta[:parameters] && meta2[:parameters]
@@ -45,15 +46,17 @@ module Meta
           end
         end
 
-        # 将 before_callbacks、action、after_callbacks 合并为 actions
-        action = @action_builder&.build
-        actions = before_callbacks + (action ? [action] : []) + after_callbacks
+        # 构建洋葱圈模型的 LinkedAction
+        action = AroundActionBuilder.build(
+          action: @action_builder&.build,
+          **callbacks
+        )
 
         Route.new(
           path: @path,
           method: @method,
           meta: meta2,
-          actions: actions
+          action: action
         )
       end
 

data/meta-api.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name          = "meta-api"
-  spec.version       = "0.0.3"
+  spec.version       = "0.0.4"
   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.3
+  version: 0.0.4
 platform: ruby
 authors:
 - yetrun
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-04-04 00:00:00.000000000 Z
+date: 2023-04-18 00:00:00.000000000 Z
 dependencies: []
 description: 一个 Web API 框架，该框架采用定义元信息的方式编写 API，并同步生成 API 文档
 email:
@@ -81,6 +81,7 @@ files:
 - lib/meta/application.rb
 - lib/meta/application/application.rb
 - lib/meta/application/execution.rb
+- lib/meta/application/linked_action.rb
 - lib/meta/application/metadata.rb
 - lib/meta/application/parameters.rb
 - lib/meta/application/path_matching_mod.rb
@@ -110,6 +111,7 @@ files:
 - lib/meta/rails.rb
 - lib/meta/route_dsl/action_builder.rb
 - 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