Node.jsのquerystringモジュールを使いこなす：URLクエリ文字列の解析と生成方法

Node.jsにおいて、URLの一部として情報を送受信するために欠かせないのがクエリ文字列の処理です。

WebアプリケーションやAPIを開発する際、クライアントから送られてくる検索パラメータやページング情報を解析する場面は非常に多く存在します。

Node.js標準のquerystringモジュールを使用すれば、これらの複雑な文字列操作を直感的かつ効率的に行うことが可能です。

本記事では、このquerystringモジュールの基本的な仕組みから、実践的な解析・生成方法までを詳しく解説します。

querystringモジュールとは

Node.jsのquerystringモジュールは、URLのクエリ文字列を解析してJavaScriptのオブジェクトに変換したり、その逆の操作を行ったりするためのツールです。

クエリ文字列とは、URLの末尾に?から始まる形式で記述される「キー=値」のペアの集合を指します。

モダンなNode.js環境では、WHATWG規格に準拠したURLSearchParams APIも利用可能ですが、特定のパフォーマンス要件やレガシーなシステムとの互換性を保つ場合には現在もこのモジュールが重宝されます。

このモジュールはNode.jsの組み込みモジュールであるため、追加のパッケージをインストールすることなく、requireまたはimportを使用してすぐに利用を開始できます。

モジュールの読み込み方法

querystringモジュールを使用するには、まずプログラムの冒頭でモジュールをインポートする必要があります。

CommonJS形式とESモジュール形式のどちらでも利用可能ですが、まずは基本的なCommonJSでの読み込み例を確認しましょう。

// CommonJS形式での読み込み
const querystring = require('node:querystring');

Node.jsの組み込みモジュールであることを明示するために、node:プリフィックスを付けて呼び出すことが推奨されています。

URLクエリ文字列をオブジェクトに解析する

受信したURLに含まれるクエリ文字列を、プログラムで扱いやすいJavaScriptオブジェクトに変換するのがquerystring.parse()メソッドです。

例えば、APIエンドポイントが受け取ったリクエストから、検索キーワードやソート順序を取得する際に多用されます。

querystring.parse() の基本的な使い方

このメソッドは、第一引数に解析したいクエリ文字列を受け取り、解析結果をオブジェクトとして返却します。

const querystring = require('node:querystring');

// 解析対象のクエリ文字列
const query = 'search=nodejs&page=2&tag=javascript&tag=backend';

// 文字列を解析してオブジェクトに変換
const parsed = querystring.parse(query);

console.log(parsed);

{
  search: 'nodejs',
  page: '2',
  tag: ['javascript', 'backend']
}

実行結果を確認すると、同じキーが複数回登場する場合（今回の例ではtag）は、自動的に配列として処理されることがわかります。

このように、複数の値を持つパラメータを柔軟に扱える点がこのメソッドの大きな特徴です。

解析時の詳細なカスタマイズ

querystring.parse()は、第2引数以降を指定することで、デフォルトの挙動を変更することができます。

例えば、区切り文字がアンパサンド & ではなくセミコロン ; である特殊な形式のデータを扱う場合も、オプションで対応可能です。

const query = 'name:John;age:25;city:Tokyo';

// 区切り文字をセミコロン、代入文字をコロンとして解析
const customParsed = querystring.parse(query, ';', ':');

console.log(customParsed);

{
  name: 'John',
  age: '25',
  city: 'Tokyo'
}

このように、APIの仕様に合わせて解析ルールを柔軟に変更できるため、多様なデータ形式に対応できます。

オブジェクトからクエリ文字列を生成する

解析とは逆に、JavaScriptのオブジェクトをURLクエリ文字列の形式に変換するのがquerystring.stringify()メソッドです。

外部のAPIに対してリクエストを送信する際など、パラメータを正しいURL形式にエンコードする必要がある場面で非常に役立ちます。

querystring.stringify() の基本的な使い方

オブジェクトを引数に渡すだけで、適切な形式の文字列を自動的に生成してくれます。

const querystring = require('node:querystring');

const params = {
  keyword: 'Node.js解説',
  category: 'programming',
  tags: ['web', 'backend']
};

// オブジェクトをクエリ文字列に変換
const queryString = querystring.stringify(params);

console.log(queryString);

keyword=Node.js%E8%A7%A3%E8%AA%AC&category=programming&tags=web&tags=backend

日本語などのマルチバイト文字は、自動的にURLエンコード（パーセントエンコーディング）されるため、開発者が手動でエンコード処理を行う必要はありません。

出力形式のカスタマイズ

生成時にも、解析時と同様に区切り文字や代入文字を指定することが可能です。

const params = { id: 100, type: 'admin' };

// 区切り文字を '|'、代入文字を '=' に設定
const customString = querystring.stringify(params, '|');

console.log(customString);

id=100|type=admin

特定のシステム要件で特殊なデリミタが求められる場合に重宝する機能です。

エスケープ処理のカスタマイズ

querystringモジュールには、文字列のエンコードとデコードを個別に行うためのメソッドも用意されています。

通常はparseやstringifyの内部で自動的に呼び出されますが、独自のエスケープ処理を定義したい場合には直接利用することもあります。

escapeとunescapeメソッド

querystring.escape()は文字列をURLエンコードし、querystring.unescape()はエンコードされた文字列を元の形式に戻します。

const querystring = require('node:querystring');

const original = 'こんにちは Node.js';
const escaped = querystring.escape(original);
const unescaped = querystring.unescape(escaped);

console.log('Escaped:', escaped);
console.log('Unescaped:', unescaped);

Escaped: %E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF%20Node.js
Unescaped: こんにちは Node.js

特定の特殊文字を除外してエンコードしたい場合などは、これらのメソッドをオーバーライドすることでカスタマイズも可能です。

querystring利用時の注意点とセキュリティ

querystringモジュールを使用する際には、いくつか注意すべき重要なポイントがあります。

特に、外部からの入力を処理する場合にはセキュリティ上のリスクを考慮しなければなりません。

キーの最大数制限（maxKeys）

querystring.parse()には、解析するキーの最大数を制限するmaxKeysというオプションがあります。

デフォルトでは1000に設定されており、これを超えるキーが含まれる場合は解析が途中で打ち切られます。

// 最大10個までのキーのみ解析を許可する
const limitedParsed = querystring.parse(longQueryString, null, null, { maxKeys: 10 });

これは、大量のパラメータを送りつけることでサーバーのCPUリソースを枯渇させるDoIS攻撃（Denial of Service）を防ぐための重要な仕様です。

もし大量のデータをクエリ文字列でやり取りする必要がある場合は、この値を調整するか、リクエストボディ（JSONなど）の使用を検討してください。

型に関する注意

querystring.parse()によって解析された値は、基本的にすべて文字列として扱われます。

数値や真偽値（true/false）として処理したい場合は、解析後に手動で型変換を行う必要があります。

const parsed = querystring.parse('id=123&active=true');

console.log(typeof parsed.id); // 'string'
const id = Number(parsed.id); // 数値に変換

この特性を理解しておかないと、数値の比較演算などで意図しないバグを引き起こす可能性があるため注意しましょう。

URLSearchParamsとの違い

現在のNode.jsでは、ブラウザ環境でも利用される標準規格であるURLSearchParamsクラスが推奨される場面が増えています。

ここでは、querystringモジュールとURLSearchParamsの主な違いを整理します。

基本的には、モダンなWeb標準に従う「URLSearchParams」を優先して使用するのが望ましいです。

しかし、極限までパフォーマンスを追求する内部ロジックや、特定のデリミタ（セミコロンなど）を使用しなければならないケースでは、依然としてquerystringモジュールが優位性を持ちます。

実践：APIリクエストのURL構築

実際の開発現場でquerystring.stringify()がどのように使われるか、具体的なHTTPリクエストの例を見てみましょう。

外部APIにクエリパラメータを付与してリクエストを投げる際、手動で文字列を連結するのはミスのもとです。

const https = require('node:https');
const querystring = require('node:querystring');

const baseUrl = 'https://api.example.com/v1/search';
const params = {
  q: 'Node.js 2026',
  limit: 20,
  lang: 'ja'
};

// クエリ文字列の構築
const fullUrl = `${baseUrl}?${querystring.stringify(params)}`;

console.log('Request URL:', fullUrl);

// 実際のリクエスト送信（イメージ）
// https.get(fullUrl, (res) => { ... });

Request URL: https://api.example.com/v1/search?q=Node.js%202026&limit=20&lang=ja

このように、オブジェクト形式でパラメータを管理することで、コードの可読性とメンテナンス性が大幅に向上します。

まとめ

Node.jsのquerystringモジュールは、シンプルながらも強力なクエリ文字列の解析・生成機能を提供します。

parse()メソッドを使えば複雑なURLパラメータを即座にオブジェクト化でき、stringify()メソッドを使えば安全なエンコードを伴う文字列生成が可能です。

現代のNode.js開発においては、WHATWG標準のURLSearchParamsとの使い分けが重要になります。

高いパフォーマンスが求められるシーンや、特殊な区切り文字を扱う必要がある場合には、迷わずquerystringモジュールを選択しましょう。

一方で、汎用的なWeb標準に基づいたコードを書きたい場合は、新しいAPIの利用を検討してください。

今回解説した特性や注意点を踏まえ、開発シーンに応じた最適なクエリ文字列処理の実装を目指しましょう。