Skip to content

README_ja.md

Latest commit

 

History

History
124 lines (92 loc) · 4.35 KB

README_ja.md

File metadata and controls

124 lines (92 loc) · 4.35 KB

StructuredParams

English | 日本語

Rails で型安全な API パラメータバリデーションとフォームオブジェクトを実現する gem

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

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

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

主な特徴

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

クイックスタート

# インストール
gem 'structured_params'

# 初期化
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

# コントローラーで使用
# permit は params.require(:user_registration).permit(...) を内部で呼び出す
# API と異なり、フォームオブジェクトでは require によるキー絞り込みが必要なため permit を使う
def create
  form = UserRegistrationForm.new(UserRegistrationForm.permit(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 の条件の下でオープンソースとして利用可能です。