rails_api_base 1.0.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fb904521fc43085746d44855945b2705573c9957abceef8691e2d8efd02a8cba
+  data.tar.gz: 8a5baa7e4fba53842e804cdb4e92763a372693ac254e0d7cdfba9f54637125f0
+SHA512:
+  metadata.gz: 6fa8391f02e591ca8f378a116d2380304a54f76520044018d076aeac9c1a2e6be7c17a3d262178a17fa89f4c6246d72e519bb467ddd1b3dca52fb196f6ffa998
+  data.tar.gz: c5caf86b40ef20edd0c33c5df1371a11a9382a2e6cd2addfcb4670e6659880922bdff44ed6e0d65dc5f4c6c76721d21197933b826b2017324f3333f65a8b6c4e

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright aric.zheng
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,19 @@
+# rails_api_base
+> 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`)
+- CRUD scaffolding (index/show/create/update/destroy)
+- Customizable response codes
+- N+1 safe (with proper `includes` in controller)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'rails_api_base'
+gem 'blueprinter'

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/assets/stylesheets/rails_api_base/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/concerns/blueprint_options_support.rb

@@ -0,0 +1,55 @@
+# app/controllers/concerns/blueprint_options_support.rb
+module BlueprintOptionsSupport
+  extend ActiveSupport::Concern
+
+  included do
+    # 声明 DSL
+    class << self
+      def blueprint_options_default(*modes)
+        @blueprint_modes = modes
+      end
+
+      def blueprint_modes
+        # 支持继承：如果子类没定义，就继承父类的设置
+        if instance_variable_defined?(:@blueprint_modes)
+          @blueprint_modes
+        else
+          superclass.respond_to?(:blueprint_modes) ? superclass.blueprint_modes : []
+        end
+      end
+    end
+  end
+
+  # === 主入口 ===
+  def blueprint_options
+    opts = {}
+    self.class.blueprint_modes.each do |mode|
+      method_name = "blueprint_options_for_#{mode}"
+      if respond_to?(method_name, true)
+        opts.merge!(send(method_name))
+      else
+        Rails.logger.warn("[BlueprintOptionsSupport] Unknown mode: #{mode}")
+      end
+    end
+    opts
+  end
+
+  private
+
+  # === 模式定义区 ===
+  def blueprint_options_for_defaults
+    { params: params }
+  end
+
+  def blueprint_options_for_fields
+    return {} unless params[:fields].present?
+
+    fields = params[:fields].split(",").map(&:strip).map(&:to_sym)
+    { fields: fields }
+  end
+
+  # 你未来还可以轻松扩展：
+  # def blueprint_options_for_locale
+  #   { locale: I18n.locale }
+  # end
+end

data/app/controllers/rails_api_base/application_controller.rb

@@ -0,0 +1,4 @@
+module RailsApiBase
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/rails_api_base/base_controller.rb

@@ -0,0 +1,111 @@
+# app/controllers/rails_api_base/base_controller.rb
+module RailsApiBase
+  class BaseController < ActionController::API
+    include BlueprintOptionsSupport
+    
+    # 默认开启 :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
+    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
+    end
+
+    # === 允许子类自定义响应 code ===
+    def response_code_for(action, **context)
+      status = context[:status] || :ok
+      if status.is_a?(Integer)
+        status
+      else
+        Rack::Utils::SYMBOL_TO_STATUS_CODE.fetch(status, 200)
+      end
+    end
+
+    # === CRUD 基础动作 ===
+    before_action :set_resource, only: %i[show update destroy]
+
+    def index
+      items = collection
+      data = serialize_collection(items)
+      render_success(data)
+    end
+
+    def show
+      data = serialize_resource(resource)
+      render_success(data)
+    end
+
+    def create
+      resource = resource_class.new(resource_params)
+      if resource.save
+        data = serialize_resource(resource)
+        render_success(data, status: :created, message: "Created successfully")
+      else
+        render_error(message: "Validation failed", errors: resource.errors.full_messages)
+      end
+    end
+
+    def update
+      if resource.update(resource_params)
+        data = serialize_resource(resource)
+        render_success(data, message: "Updated successfully")
+      else
+        render_error(message: "Validation failed", errors: resource.errors.full_messages)
+      end
+    end
+
+    def destroy
+      resource.destroy
+      render_success(nil, message: "Deleted successfully")
+    end
+
+    private
+
+    # === 序列化逻辑 ===
+    def serialize_resource(resource)
+      bp = blueprint_class
+      bp ? bp.render_as_hash(resource, **blueprint_options) : resource.as_json
+    end
+
+    def serialize_collection(collection)
+      bp = blueprint_class
+      bp ? bp.render_as_hash(collection, **blueprint_options) : collection.as_json
+    end
+
+    def blueprint_class
+      "#{resource_class}Blueprint".constantize
+    rescue NameError
+      nil
+    end
+
+    # === 资源推导 ===
+    def resource_class
+      controller_name.singularize.classify.constantize
+    end
+
+    def resource
+      instance_variable_get("@#{controller_name.singularize}")
+    end
+
+    def set_resource
+      instance_variable_set("@#{controller_name.singularize}", resource_class.find(params[:id]))
+    rescue ActiveRecord::RecordNotFound
+      render_error(message: "Record not found", status: :not_found)
+    end
+
+    def collection
+      resource_class.all
+    end
+
+    def resource_params
+      raise NotImplementedError, "Subclass must implement ##{controller_name.singularize}_params"
+    end
+  end
+end

data/app/helpers/rails_api_base/application_helper.rb

@@ -0,0 +1,4 @@
+module RailsApiBase
+  module ApplicationHelper
+  end
+end

data/app/jobs/rails_api_base/application_job.rb

@@ -0,0 +1,4 @@
+module RailsApiBase
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/rails_api_base/application_mailer.rb

@@ -0,0 +1,6 @@
+module RailsApiBase
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/rails_api_base/application_record.rb

@@ -0,0 +1,5 @@
+module RailsApiBase
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/views/layouts/rails_api_base/application.html.erb

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Rails api base</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= yield :head %>
+
+  <%= stylesheet_link_tag    "rails_api_base/application", media: "all" %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,2 @@
+RailsApiBase::Engine.routes.draw do
+end

data/lib/rails_api_base/engine.rb

@@ -0,0 +1,5 @@
+module RailsApiBase
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsApiBase
+  end
+end

data/lib/rails_api_base/version.rb

@@ -0,0 +1,3 @@
+module RailsApiBase
+  VERSION = "1.0.5"
+end

data/lib/rails_api_base.rb

@@ -0,0 +1,10 @@
+# lib/rails_api_base.rb
+require "blueprinter"
+require "rails_api_base/engine"
+
+module RailsApiBase
+  # 可选：提供便捷引用
+  def self.base_controller
+    RailsApiBase::BaseController
+  end
+end

data/lib/tasks/rails_api_base_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :rails_api_base do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: rails_api_base
+version: !ruby/object:Gem::Version
+  version: 1.0.5
+platform: ruby
+authors:
+- aric.zheng
+bindir: bin
+cert_chain: []
+date: 2025-11-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: blueprinter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: kaminari
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Standardized JSON API foundation for Rails apps.
+email:
+- 1290657123@qq.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/stylesheets/rails_api_base/application.css
+- app/controllers/concerns/blueprint_options_support.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
+- app/jobs/rails_api_base/application_job.rb
+- app/mailers/rails_api_base/application_mailer.rb
+- app/models/rails_api_base/application_record.rb
+- app/views/layouts/rails_api_base/application.html.erb
+- config/routes.rb
+- lib/rails_api_base.rb
+- lib/rails_api_base/engine.rb
+- lib/rails_api_base/version.rb
+- lib/tasks/rails_api_base_tasks.rake
+homepage: https://js.work
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  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
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.3
+specification_version: 4
+summary: Standardized JSON API foundation for Rails apps.
+test_files: []