rails_api_base 1.0.6 → 1.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2da130825a1eb93bcdb92862f36f4e3f62ccc037b0727d6f8c936a79ebf369ca
-  data.tar.gz: fa81a3cd03d67dd6696f0ce21f6b314e932d0e5bea4ab93d805087ec5eff8d92
+  metadata.gz: e18fba691675d980ac2aa985b2e390aa45acae166602faf8601ced9820b31dc0
+  data.tar.gz: 615cfd471a33904767ef6502690355d984541f57644676905759900076de2307
 SHA512:
-  metadata.gz: 6bdb9e7db069e7da7370d1516786fdc21936b401971b82b3d6558aeb626eb958523eac3ad3efce309f13341fef6b3e2e066170569fa8e4087ceb5b60400dac49
-  data.tar.gz: 32752db03260bd4dba4a25dd1a9cc439f53ff04983aaa2fea7219d70623d44add188e23c7d510ac5b0fea5b9a067b83e5cb7a9d656c89492aad5a91706e9db24
+  metadata.gz: b5863ec6fdd7373b4d91d1c05fc6dc0b87f4766ba00f7a565ae499ab8e793812c1ee644f98df81791f7bc575aa9122de15aad153676a278425da3174e600ec85
+  data.tar.gz: 3faa7cdf902519e04b11cb6843f988131611be27f5cb595635603d8cfe4ef2541fe3740e8e5bff896399fe7c37f1e878581d7089b50b4e493449da3cf6b24544

data/README.md

@@ -2,7 +2,6 @@
 > Standardized JSON API base controller for Rails with Blueprinter support.
 
 ## Features
-
 - Unified response format: `{ code, msg, data }`
 - Field selection via `?fields=title,user`
 - Auto Blueprinter integration (`PostBlueprint`)
@@ -11,9 +10,46 @@
 - N+1 safe (with proper `includes` in controller)
 
 ## Installation
-
 Add to your Gemfile:
 
 ```ruby
 gem 'rails_api_base'
-gem 'blueprinter'
+gem 'blueprinter'
+```
+
+## Usage
+- ./app/blueprints/post_blueprint.rb
+- ./app/controllers/posts_controller.rb
+
+```rb
+# blueprint file - optimize version(dynamic_fields)
+class PostBlueprint < Blueprinter::Base
+  identifier :id
+  fields :title, :content
+
+  # === 动态注册可选字段 ===
+  dynamic_fields = [:user, :tags]
+
+  dynamic_fields.each do |field_name|
+    field field_name, if: ->(_, model, options) {
+      Array(options[:fields]).include?(field_name)
+    }
+  end
+end
+
+# posts controller
+class PostsController < RailsApiBase::BaseController
+  blueprint_options_default :fields
+
+  private
+  def collection
+    Post.includes(:user, :tags)
+        .page(params[:page])
+        .per(params[:size] || 10)
+  end
+
+  def post_params
+    params.require(:post).permit(:title, :content)
+  end
+end
+```

data/app/controllers/concerns/blueprint_options_support.rb

@@ -52,4 +52,4 @@ module BlueprintOptionsSupport
   # def blueprint_options_for_locale
   #   { locale: I18n.locale }
   # end
-end
+end

data/app/controllers/concerns/queryable.rb

@@ -0,0 +1,179 @@
+# app/controllers/concerns/rails_api_base/queryable.rb
+module Queryable
+  extend ActiveSupport::Concern
+
+  DEFAULT_CONFIG = {
+    pagination: {
+      enabled: false,
+      page_param: :page,
+      per_param: :size,
+      default_per: 10,
+      max_per: 100
+    },
+    sorting: {
+      enabled: false,
+      sort_param: :sort,
+      default_direction: :asc,
+      allowed_fields: []
+    },
+    searching: {
+      enabled: false,
+      search_param: :q,
+      searchable_fields: []
+    },
+    filtering: {
+      enabled: false,
+      filter_param: :filter,
+      filterable_fields: []
+    },
+    meta: {
+      enabled: true,
+      rows_key: :rows,
+      total_key: :total
+    }
+  }.freeze
+
+  class_methods do
+    def supports_query(user_config = {})
+      config = DEFAULT_CONFIG.deep_dup
+      user_config.each do |key, value|
+        if config.key?(key) && value.is_a?(Hash)
+          config[key].merge!(value)
+        else
+          config[key] = value
+        end
+      end
+
+      define_method(:query_config) { config }
+      include InstanceMethods
+    end
+  end
+
+  module InstanceMethods
+    def apply_query_with_meta(scope)
+      config = query_config
+      meta = {}
+
+      # 应用过滤、搜索、排序（不分页）
+      base_scope = scope
+      base_scope = apply_filtering(base_scope)    if config[:filtering][:enabled]
+      base_scope = apply_searching(base_scope)    if config[:searching][:enabled]
+      base_scope = apply_sorting(base_scope)      if config[:sorting][:enabled]
+
+      # 获取总数（用于 meta）
+      if config[:meta][:enabled]
+        meta[config[:meta][:total_key]] = base_scope.count
+      end
+
+      # 应用分页
+      paginated_scope = base_scope
+      if config[:pagination][:enabled]
+        paginated_scope = apply_pagination(base_scope)
+      end
+
+      {
+        collection: paginated_scope,
+        meta: config[:meta][:enabled] ? meta : nil
+      }
+    end
+
+    private
+
+    def apply_pagination(scope)
+      config = query_config[:pagination]
+      page = [params[config[:page_param]].to_i, 1].max
+      per_input = params[config[:per_param]].to_i
+      per = per_input <= 0 ? config[:default_per] : [per_input, config[:max_per]].min
+      per = [per, 1].max
+      scope.page(page).per(per)
+    end
+
+    def apply_sorting(scope)
+      config = query_config[:sorting]
+      sort_param = params[config[:sort_param]]
+      return scope unless sort_param.present?
+
+      direction = sort_param.start_with?('-') ? :desc : :asc
+      field = sort_param.delete_prefix('-').to_sym
+      connection = scope.connection
+
+      if config[:allowed_fields].empty? || config[:allowed_fields].include?(field)
+        quoted_field = connection.quote_column_name(field)
+        return scope.order(Arel.sql("#{quoted_field} #{direction}"))
+      else
+        return scope
+      end
+    end
+
+    def sanitize_sql_order(field, direction)
+      direction = %i[asc desc].include?(direction) ? direction : :asc
+      "#{connection.quote_column_name(field)} #{direction}"
+    end
+
+    def apply_searching(scope)
+      config = query_config[:searching]
+      term = params[config[:search_param]]&.strip
+      return scope unless term.present?
+
+      searchable_fields = config[:searchable_fields]
+      return scope if searchable_fields.empty?
+
+      connection = scope.connection
+
+      terms = Array.new(searchable_fields.size, "%#{term}%")
+      conditions = searchable_fields.map do |f|
+        "LOWER(#{connection.quote_column_name(f)}) LIKE LOWER(?)"
+      end.join(' OR ')
+      scope.where(conditions, *terms)
+    end
+
+    def apply_filtering(scope)
+      config = query_config[:filtering]
+      raw_filters = params[config[:filter_param]]
+      return scope if raw_filters.blank?
+
+      # 1. 获取允许过滤的字段名（字符串数组）
+      filterable_fields = config[:filterable_fields].map(&:to_s)
+
+      # 2. permit 这些字段（包括嵌套操作符，如 filter[status][eq]）
+      permitted = raw_filters.permit(filterable_fields.map { |f| "#{f}" } +
+                                       filterable_fields.map { |f| "#{f}.*" })
+
+      # 3. 转为普通 Hash
+      filters = permitted.to_h
+
+      connection = scope.connection
+
+      filters.inject(scope) do |s, (field, value)|
+        if value.is_a?(Hash)
+          op = value.keys.first&.to_sym
+          val = value.values.first
+          apply_filter_operation(s, field, op, val)
+        else
+          s.where("#{connection.quote_column_name(field)} = ?", val_or_array(value))
+        end
+      end
+    end
+
+    def apply_filter_operation(scope, field, op, value)
+      connection = scope.connection
+      quoted = connection.quote_column_name(field)
+      case op
+      when :eq  then scope.where("#{quoted} = ?", val_or_array(value))
+      when :neq then scope.where("#{quoted} != ?", val_or_array(value))
+      when :gt  then scope.where("#{quoted} > ?", value)
+      when :gte then scope.where("#{quoted} >= ?", value)
+      when :lt  then scope.where("#{quoted} < ?", value)
+      when :lte then scope.where("#{quoted} <= ?", value)
+      when :in  then scope.where(quoted => Array(value))
+      when :nin then scope.where.not(quoted => Array(value))
+      else scope
+      end
+    end
+
+    def val_or_array(val)
+      return val unless val.is_a?(String) && val.include?(',')
+      val.split(',').map(&:strip)
+    end
+  end
+end

data/app/controllers/rails_api_base/base_controller.rb

@@ -2,20 +2,21 @@
 module RailsApiBase
   class BaseController < ActionController::API
     include BlueprintOptionsSupport
-    
+    include Queryable
+
     # 默认开启 :defaults 模式
     blueprint_options_default :defaults
 
     # === 统一成功响应 ===
     def render_success(data, status: :ok, message: "success", code: nil)
       code ||= response_code_for(action_name, status: status)
-      render json: { code: code, msg: message,  data: data }, status: status
+      render json: { code: code, msg: message, data: data }, status: status
     end
 
     # === 统一错误响应 ===
     def render_error(message: "Unprocessable Entity", status: :unprocessable_entity, errors: nil)
       code = response_code_for(action_name, status: status)
-      render json: { code: code, msg: message,  errors: errors }, status: status
+      render json: { code: code, msg: message, errors: errors }, status: status
     end
 
     # === 允许子类自定义响应 code ===
@@ -32,8 +33,11 @@ module RailsApiBase
     before_action :set_resource, only: %i[show update destroy]
 
     def index
-      items = collection
-      data = serialize_collection(items)
+      result = apply_query_with_meta(collection)
+      data = {
+        query_config[:meta][:rows_key] => serialize_collection(result[:collection]),
+      }
+      data.merge!(result[:meta]) if result[:meta]
       render_success(data)
     end
 
@@ -44,7 +48,8 @@ module RailsApiBase
 
     def create
       resource = resource_class.new(resource_params)
-      if resource.save
+      if before_save(resource) && resource.save
+        after_save(resource)
         data = serialize_resource(resource)
         render_success(data, status: :created, message: "Created successfully")
       else
@@ -53,7 +58,8 @@ module RailsApiBase
     end
 
     def update
-      if resource.update(resource_params)
+      if before_save(resource) && resource.update(resource_params)
+        after_save(resource)
         data = serialize_resource(resource)
         render_success(data, message: "Updated successfully")
       else
@@ -61,6 +67,22 @@ module RailsApiBase
       end
     end
 
+    # === 可选：通用钩子（默认调用 create/update 钩子）===
+    def before_save(resource)
+      action_name == "create" ? before_create(resource) : before_update(resource)
+    end
+
+    def after_save(resource)
+      action_name == "create" ? after_create(resource) : after_update(resource)
+    end
+
+    # === 子类覆盖这些 ===
+    def before_create(resource); true; end
+    def after_create(resource); end
+
+    def before_update(resource); true; end
+    def after_update(resource); end
+
     def destroy
       resource.destroy
       render_success(nil, message: "Deleted successfully")
@@ -90,6 +112,10 @@ module RailsApiBase
       controller_name.singularize.classify.constantize
     end
 
+    def resource_key
+      controller_name.singularize.underscore.to_sym
+    end
+
     def resource
       instance_variable_get("@#{controller_name.singularize}")
     end
@@ -105,7 +131,9 @@ module RailsApiBase
     end
 
     def resource_params
-      raise NotImplementedError, "Subclass must implement ##{controller_name.singularize}_params"
+      # raise NotImplementedError, "Subclass must implement ##{controller_name.singularize}_params"
+      permitted_params = params.require(resource_key)
+      permitted_params.permit!
     end
   end
-end
+end

data/lib/rails_api_base/version.rb

@@ -1,3 +1,3 @@
 module RailsApiBase
-  VERSION = "1.0.6"
+  VERSION = "1.0.8"
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_api_base
 version: !ruby/object:Gem::Version
-  version: 1.0.6
+  version: 1.0.8
 platform: ruby
 authors:
 - aric.zheng
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-06 00:00:00.000000000 Z
+date: 2025-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -49,6 +50,7 @@ files:
 - Rakefile
 - app/assets/stylesheets/rails_api_base/application.css
 - app/controllers/concerns/blueprint_options_support.rb
+- app/controllers/concerns/queryable.rb
 - app/controllers/rails_api_base/application_controller.rb
 - app/controllers/rails_api_base/base_controller.rb
 - app/helpers/rails_api_base/application_helper.rb
@@ -69,6 +71,7 @@ metadata:
   homepage_uri: https://js.work
   source_code_uri: https://github.com/afeiship/rails_api_base
   changelog_uri: https://github.com/afeiship/rails_api_base/blob/master/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -83,7 +86,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.3
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Standardized JSON API foundation for Rails apps.
 test_files: []