Skip to content

README_ja.md

Latest commit

 

History

History
126 lines (94 loc) · 4.37 KB

README_ja.md

File metadata and controls

126 lines (94 loc) · 4.37 KB
Raw

StructuredParams

English | 日本語

Rails の型付きパラメータオブジェクトとフォームオブジェクトを提供する gem。

対応範囲は Ruby 3.2+、Rails / ActiveModel 7.2 以上 9.0 未満です。

StructuredParams は、以下の課題を解決します：

  • API エンドポイント: リクエストパラメータの型チェック、バリデーション、型変換
  • フォームオブジェクト: 複雑なフォーム入力の検証とモデル変換

ActiveModel をベースに、ネストしたオブジェクトや配列も簡潔に扱えます。

主な機能

  • ✅ API パラメータバリデーション - 型安全なリクエスト検証
  • ✅ フォームオブジェクト - 複雑なフォームロジックをカプセル化
  • ✅ ネスト構造のサポート - object / array の自動キャスト
  • ✅ Strong Parameters 連携 - permit リストの自動生成
  • ✅ ActiveModel 互換 - バリデーション、シリアライズなど標準機能を利用可能
  • ✅ RBS 型定義 - 型安全な開発体験

クイックスタート

# Gemfile
gem 'structured_params'

# config/initializers/structured_params.rb
StructuredParams.register_types

1. API パラメータバリデーション

class AddressParams < StructuredParams::Params
  attribute :street, :string
  attribute :city, :string
end

class UserParams < StructuredParams::Params
  attribute :name, :string
  attribute :age, :integer
  attribute :score, :integer
  attribute :tags, :array, value_type: :string           # プリミティブ配列
  attribute :address, :object, value_class: AddressParams # ネストオブジェクト

  # 型変換前の生文字列をバリデーション
  validates_raw :score, format: { with: /\A\d+\z/, message: 'must be numeric string' }
  validates :name, presence: true
  validates :age, numericality: { greater_than: 0 }
  validates :score, numericality: { greater_than_or_equal_to: 0 }
end

# API コントローラーで使用
def create
  user_params = UserParams.new(params)

  if user_params.valid?
    User.create!(user_params.attributes)
  else
    render json: { errors: user_params.errors }, status: :unprocessable_entity
  end
end

プリミティブ配列

value_type を使うとプリミティブ型の配列を扱えます。Strong Parameters では配列フォーマット（tags: []）で許可されます。

class UserParams < StructuredParams::Params
  attribute :tags, :array, value_type: :string
end

# Strong Parameters と同等:
# params.permit(tags: [])

2. フォームオブジェクト

class UserRegistrationForm < StructuredParams::Params
  attribute :name, :string
  attribute :email, :string
  attribute :terms_accepted, :boolean

  validates :name, :email, presence: true
  validates :terms_accepted, acceptance: true
end

# コントローラーで使用
# ActionController::Parameters を Form クラスに渡すと、内部で
# params.require(:user_registration).permit(...) が自動的に呼ばれます。
# この挙動を使うには、クラス名を `Form` で終わらせてください。
def create
  form = UserRegistrationForm.new(params)

  if form.valid?
    User.create!(form.attributes)
    redirect_to root_path
  else
    render :new
  end
end

ドキュメント

コントリビューション

バグレポートやプルリクエストは GitHub の https://github.com/Syati/structured_params で歓迎しています。

ライセンス

この gem は MIT License のもとで公開されています。