Microsoft developer platform documentation update: Remove Deprecated use of url.parse で最初に確認すべき結論は、typed-rest-client のURL解析が、Node.jsのレガシーAPIである url.parse() から WHATWG準拠の new URL() に移行される点です。対応が必要なのは、Node.js 24以降への移行を進めている開発チーム、typed-rest-client を直接または間接的に使っているMicrosoft developer platform関連ツールの利用者、そしてリクエストURL・プロキシ・リダイレクト・認証付きURLを独自に扱っている実装です。
今回の変更は「非推奨APIを置き換えるだけ」と見ると見落としが出ます。new URL() は url.parse() と完全な互換動作ではなく、不正なURLで例外を投げる、相対URLにはbaseが必要になる、auth や path などのプロパティ構造が変わる、といった違いがあります。PR上では2026年5月5日に追加コミットが入り、package.json のバージョン更新も含まれていますが、確認時点ではPRとして表示されているため、実運用ではリリース済みバージョンとロックファイルを必ず確認してください。(GitHub)
Microsoft developer platformで何が変わるのか
今回の対象は、Microsoftの microsoft/typed-rest-client リポジトリにある「Remove Deprecated use of url.parse」というPRです。typed-rest-client はTypeScript向けの軽量なREST/HTTPクライアントで、REST/HTTPクライアント、認証、プロキシ、証明書、リダイレクトなどを扱うライブラリとして説明されています。(GitHub)
PRの目的は、Node.jsで非推奨扱いが強まっている url.parse() の利用をやめ、より標準的な WHATWG URL API、つまり new URL() に移すことです。PR本文でも「Node 24のDeprecation」「url.parse からより安全な New URL() へ更新」「rest-clientのrequest object形成に影響する」と説明されています。(GitHub)
変更点の全体像
| 確認項目 | 変更内容 | 実務上の意味 |
|---|---|---|
| URL解析 | url.parse() から new URL() に変更 | 不正なURLや相対URLの扱いが変わる可能性がある |
| 型定義 | url.Url から URL へ変更 | parsedUrl.auth や parsedUrl.path に依存したコードは見直しが必要 |
| リクエスト生成 | RequestInfo.parsedUrl がWHATWG URL になる | カスタム処理やテストの期待値が変わる可能性がある |
| リダイレクト | リダイレクト先URLを new URL(redirectUrl, parsedUrl.href) で解決 | 相対リダイレクトの扱いをテストすべき |
| プロキシ | プロキシURLも new URL() で解析 | 不正なプロキシURLは早い段階でエラーになりやすい |
| URL結合 | Util.getUrl() のbase/resource結合ロジックを更新 | base URL、相対パス、末尾スラッシュの挙動確認が重要 |
| パッケージ | PR上で 2.3.1 から 2.3.2 への変更が含まれる | 実際にnpmで取得されるバージョンは別途確認が必要 |
PRの差分では、lib/HttpClient.ts、lib/Interfaces.ts、lib/Util.ts、package.json、package-lock.json、test/units/utiltests.ts が変更対象になっています。HttpClient.ts では url.parse() の置換、Interfaces.ts では IRequestInfo.parsedUrl の型変更、Util.ts ではURL結合処理の再実装、package.json ではバージョン更新が確認できます。(GitHub)
なぜurl.parseの削除が重要なのか
Node.jsの非推奨情報では、DEP0169として url.parse() が「Insecure url.parse()」とされています。Node.js 24ではApplication deprecationとなり、url.parse() の挙動は標準化されておらず、セキュリティ上の影響を持つエラーを起こしやすいため、WHATWG URL APIを使うよう案内されています。(Node.js)
ここで重要なのは、url.parse() だけを検索すれば終わりではない点です。Node.jsの非推奨情報では、url.format(urlString) や url.resolve() も内部的に url.parse() を呼ぶため、この非推奨の対象に含まれると説明されています。つまり、Microsoft developer platform関連のNode.js/TypeScriptコードを点検する場合は、次のAPIもまとめて検索対象に入れるべきです。(Node.js)
rg "url\.parse|url\.format|url\.resolve|url\.Url"new URL() はブラウザ互換のWHATWG URL APIで、Node.jsではグローバルオブジェクトとしても利用できます。相対URLを解析する場合はbaseが必要で、無効なURLが渡されると TypeError が投げられます。(Node.js)
const absoluteUrl = new URL("https://example.org/api/items");
const relativeUrl = new URL("/api/items", "https://example.org");この違いにより、以前は曖昧に処理されていたURLが、移行後は明確にエラーになることがあります。これはセキュリティ面では望ましい一方で、既存コードのテストや運用設定に不正確なURLが混ざっていると、アップデート後に失敗する可能性があります。
対応が必要な人と優先度
今回の変更は、すべての利用者が即座にコード修正を迫られる変更ではありません。ただし、URLを組み立てる箇所、カスタムHTTP処理、プロキシ、リダイレクトを使っている環境では、事前確認の価値が高いです。
| 対象 | 優先度 | 確認すべきこと |
|---|---|---|
| Node.js 24以降でCI/CDや開発環境を動かしている | 高 | 非推奨警告、URL関連テスト、実行時エラー |
typed-rest-client を直接利用している | 高 | インストール済みバージョン、ロックファイル、URL生成ロジック |
| Azure DevOps拡張、社内CLI、ビルドツールで間接利用している | 中〜高 | 依存関係ツリーに typed-rest-client が含まれるか |
| カスタムプロキシ、NTLM、Bearer認証、証明書、リダイレクトを使う | 高 | リクエストオプションとURLシリアライズ結果 |
| 通常の絶対URLだけでREST APIを呼んでいる | 中 | アップデート後の単体テストと疎通確認 |
| Node.jsを使わない、または該当パッケージを使わない | 低 | 直接対応は不要 |
特に注意すべきなのは、typed-rest-client を自分で意識していなくても、Microsoft関連の開発支援ツール、Azure DevOps系の拡張、古い社内ツールの依存関係に含まれているケースです。まずはプロジェクト直下で依存関係を確認しましょう。
npm ls typed-rest-clientpnpmを使っている場合は次のように確認します。
pnpm why typed-rest-clientYarnの場合は次のコマンドが使えます。
yarn why typed-rest-clientrest-clientのrequest object形成で確認すべき影響
PRの要点にある「Impacts how request object is formed by rest-client」は、実務上かなり重要です。HTTPリクエストは単にURL文字列を送るだけではなく、内部で protocol、hostname、port、path、認証情報、プロキシ、リダイレクト先などに分解されます。ここで使われるURLオブジェクトがレガシーな url.Url からWHATWG URL に変わると、コードが参照できるプロパティや文字列化の結果が変わります。
url.UrlとURLで参照方法が変わる主な項目
| 旧APIで見ていた値 | 新APIでの確認方法 | 注意点 |
|---|---|---|
parsedUrl.auth | url.username と url.password | ユーザー名とパスワードが分かれる |
parsedUrl.path | url.pathname + url.search | path という同名プロパティはない |
parsedUrl.query | url.searchParams または url.search | 文字列として扱うか、パラメータとして扱うかを分ける |
url.format(parsedUrl) | url.href | エンコード結果が変わる場合がある |
parsedUrl.host | url.host | hostはホスト名とポートを含む |
parsedUrl.hostname | url.hostname | ポートは含まない |
parsedUrl.protocol | url.protocol | 末尾の : を含む点は同じ |
たとえば、署名付きURLやHMAC署名を使っている場合、URLの文字列化結果が少し変わるだけで署名不一致になります。url.format() の結果を前提に署名していた処理は、url.href や pathname + search のどちらを使うべきかを明確にしてください。
const parsed = new URL(requestUrl);
// HTTP requestのpath相当が必要な場合
const requestPath = `${parsed.pathname}${parsed.search}`;
// URL全体が必要な場合
const fullUrl = parsed.href;移行前に確認するチェックリスト
インストール済みバージョンとPR反映状況を確認する
PR上では package.json のバージョンが 2.3.1 から 2.3.2 に変更されています。ただし、PRの差分にバージョン更新があることと、そのバージョンが実際に公開・利用可能であることは別です。確認時点ではPRはOpenとして表示されているため、利用前にnpm、GitHub Releases、ロックファイルを確認してください。(GitHub)
npm view typed-rest-client version
npm ls typed-rest-clientプロジェクトで package-lock.json、pnpm-lock.yaml、yarn.lock を使っている場合は、ロックファイル内のバージョンも確認します。CIだけ新しい依存に更新され、開発者のローカル環境では古いまま、という状態は不具合の再現を難しくします。
自社コード内のレガシーURL APIを検索する
typed-rest-client 側の変更だけでなく、自社コードにも同じ問題が残っていないか確認しましょう。Node.jsのDEP0169では url.parse() だけでなく、url.format(urlString) と url.resolve() も確認対象になります。(Node.js)
rg "url\.parse|url\.format|url\.resolve|require\(['\"]url['\"]\)|from ['\"]node:url['\"]"TypeScriptでは型名も検索します。
rg "url\.Url|IRequestInfo|parsedUrl"検索結果が出たら、単純置換ではなく「何のためにその値を使っているか」で判断してください。ホスト検証なのか、署名対象の文字列生成なのか、プロキシ設定なのかによって、移行先の書き方が変わります。
相対URLとbase URLの組み合わせをテストする
new URL() は、相対URLだけを渡すとエラーになります。相対URLを扱う場合はbase URLが必要です。Node.jsのURL APIドキュメントでも、input が相対URLの場合は base が必要で、絶対URLの場合は base が無視されると説明されています。(Node.js)
// エラーになり得る
const bad = new URL("/api/items");
// 正しい
const ok = new URL("/api/items", "https://example.org");ただし、new URL(resource, base) は万能ではありません。base URLの末尾スラッシュの有無で結果が変わるためです。
new URL("users", "https://example.org/api/v1").href
// "https://example.org/api/users"
new URL("users", "https://example.org/api/v1/").href
// "https://example.org/api/v1/users"PRの Util.getUrl() では、従来挙動をできるだけ保つためにパス結合処理を明示的に調整しています。自社コードでURL結合を置き換える場合も、「旧実装で期待していたパス」と「新実装で生成されるパス」をテストで比較してください。(GitHub)
プロキシとリダイレクトの設定を確認する
今回の変更では、プロキシURLやリダイレクトURLの解析にも new URL() が使われます。これにより、曖昧な設定や不正なURLが早期にエラーとして見つかる可能性があります。
確認すべき設定は次の通りです。
| 設定・機能 | 確認ポイント |
|---|---|
HTTP_PROXY / HTTPS_PROXY | スキーム、ホスト、ポート、認証情報が正しいか |
NO_PROXY | バイパス対象のホスト名と実際のリクエスト先が一致するか |
| リダイレクト | 相対 Location と絶対 Location の両方をテストしているか |
| HTTPSからHTTPへのリダイレクト | セキュリティ上、意図せず許可していないか |
| 認証付きURL | ユーザー名・パスワードに特殊文字がある場合にエンコードされるか |
特にプロキシ認証情報に @、:、/、スペースなどが含まれる環境では、URL文字列に直接埋め込むよりも、設定値を分けて管理した方が安全です。URLに埋め込む必要がある場合は、値が正しくパーセントエンコードされるかを確認してください。
Node.js 24でテストを実行する
Node.js 24への移行を予定している場合は、依存関係更新前後の両方でテストを実行してください。非推奨警告を見たい場合は、開発環境やCIで --trace-deprecation を使うと、どのコードから警告が出ているかを追いやすくなります。
node --trace-deprecation ./node_modules/.bin/jestアプリケーションの起動コマンドで確認する場合は次のように実行します。
node --trace-deprecation dist/index.jsただし、Node.jsのDEP0169はApplication deprecationとして説明されており、対象の扱いは実行コードの場所やNode.jsバージョンによって変わります。警告が出ないから安全と判断するのではなく、検索とテストを組み合わせて確認してください。(Node.js)
url.parseからnew URLへ移行する実装例
絶対URLを解析する
旧実装では次のように書かれていることがあります。
import url = require("url");
const parsed = url.parse(requestUrl);
const protocol = parsed.protocol;
const host = parsed.host;
const path = parsed.path;WHATWG URL APIでは次のように書き換えます。
const parsed = new URL(requestUrl);
const protocol = parsed.protocol;
const host = parsed.host;
const path = `${parsed.pathname}${parsed.search}`;parsed.path はWHATWG URL にはないため、HTTP request optionsの path に相当する値が必要なら pathname と search を結合します。
相対URLをbase URLと結合する
旧実装で url.resolve() を使っていた場合は、用途を確認してから置き換えます。
const target = new URL(resourcePath, baseUrl);ユーザー入力を扱う場合は、絶対URLが入力されたときにbase URLが無視される点に注意してください。Node.jsのドキュメントでも、input が絶対URLなら base は無視されると説明されています。(Node.js)
const baseUrl = "https://example.org/app/";
const target = new URL(userInput, baseUrl);
if (target.origin !== new URL(baseUrl).origin) {
throw new Error("許可されていない外部URLです");
}このチェックを入れないと、外部URLへのリダイレクトやSSRFにつながる可能性があります。new URL() に移行したから安全、ではなく、パース後に期待する origin、protocol、hostname を検証することが重要です。
無効なURLを明示的に扱う
new URL() は無効なURLで例外を投げます。業務アプリでは、例外を握りつぶすのではなく、ログとエラーメッセージを分けて扱いましょう。
function parseRequestUrl(input: string): URL {
try {
return new URL(input);
} catch {
throw new Error("リクエストURLの形式が正しくありません");
}
}エラーメッセージにURL全体をそのまま含めると、アクセストークン、署名、ユーザー情報をログに残す危険があります。PRでもエラーメッセージにURLを含めない方向の更新コミットが確認できます。(GitHub)
失敗しやすいポイントと対策
| 失敗しやすいポイント | 起きること | 対策 |
|---|---|---|
相対URLをそのまま new URL() に渡す | TypeError が発生する | base URLを必ず渡す |
| base URLの末尾スラッシュを確認しない | 生成されるパスが変わる | 代表パターンをテストに追加する |
parsedUrl.path を参照している | undefinedになる | pathname + search に置き換える |
parsedUrl.auth を参照している | 認証情報を取得できない | username と password を使う |
署名付きURLで href を使う | 署名対象文字列が変わる | 旧仕様と新仕様の署名対象を明文化する |
| プロキシURLが曖昧 | 起動時またはリクエスト時に失敗する | プロキシ設定をURLとして検証する |
| 不正ポートを含むURLを許容していた | 新APIではエラーになりやすい | 入力値を事前検証し、テストケースに追加する |
| 警告だけを抑制する | 将来のNode.js更新で本番障害になる | 非推奨APIを置換し、CIで検出する |
Node.jsの非推奨情報では、不正なポートを含むURLについても、旧 url.parse() では受け入れられていたケースがあり、ホスト名のなりすましにつながる可能性があると説明されています。URLの移行時は「以前動いていたから正しい」ではなく、「URLとして厳密に妥当か」を基準に見直してください。(Node.js)
実務での移行手順
まず影響範囲を洗い出す
最初に行うべきことは、ライブラリ更新ではなく影響範囲の把握です。次の順番で確認すると、手戻りを減らせます。
| 手順 | 作業 | 判断基準 |
| -: | —————————————— | —————– |
| 1 | typed-rest-client の利用有無を確認 | 直接依存・間接依存の両方を見る |
| 2 | url.parse、url.format、url.resolve を検索 | 自社コードに残っていれば移行対象 |
| 3 | Node.js 24でテスト | 非推奨警告やURLエラーを確認 |
| 4 | プロキシ・リダイレクト・認証付きURLを重点テスト | 本番設定に近い値で検証 |
| 5 | ロックファイルを固定して段階リリース | CIと本番で依存バージョンを揃える |
この順番にすると、「パッケージを上げたらどこが壊れたか分からない」という状態を避けられます。
テストケースに入れるべきURLパターン
URL関連の変更では、正常系だけのテストでは不十分です。最低限、次のパターンを用意してください。
| パターン | 例 | 見るべき結果 |
|---|---|---|
| 通常の絶対URL | https://example.org/api/items | 正しくリクエストされる |
| 相対パス | /api/items | base URLと結合される |
| base URL末尾スラッシュあり | https://example.org/api/ | 期待通りの階層になる |
| base URL末尾スラッシュなし | https://example.org/api | 意図しない親階層移動がない |
| クエリ付きURL | ?page=1&limit=20 | クエリが落ちない |
| 認証付きURL | https://user:[email protected] | 認証情報が意図通り処理される |
| 特殊文字 | スペース、日本語、@ など | エンコード結果が期待通り |
| 不正URL | 不正ポート、スキームなし | 明確にエラーになる |
| 相対リダイレクト | Location: /login | 現在URLを基準に解決される |
| HTTPSからHTTPへのリダイレクト | downgrade | 設定どおり拒否される |
特にAPIクライアントでは、URLが少し変わっただけでキャッシュキー、署名、ログ集計、監視ルールが変わることがあります。単にHTTPステータスが200になるかだけでなく、「実際に送られたURL文字列」も確認してください。
すぐにやるべき対応
今回のMicrosoft developer platform documentation update: Remove Deprecated use of url.parse を見た開発チームは、次の3つから始めるのが現実的です。
まず、現在のプロジェクトで typed-rest-client を使っているか確認します。直接依存していなくても、Azure DevOps関連ツールや社内CLIの依存に含まれていることがあります。
次に、自社コード内の url.parse()、url.format()、url.resolve()、url.Url を検索し、new URL() への移行対象を洗い出します。Node.js 24では url.parse() の非推奨が強まっており、WHATWG URL APIへの移行が推奨されています。(Node.js)
最後に、依存関係を更新する前に、base URL、相対URL、プロキシ、リダイレクト、認証付きURLのテストを追加します。new URL() はより標準的で安全な方向のAPIですが、旧APIの曖昧な挙動に依存していたコードでは、移行時に差分が出ます。PRが正式に取り込まれた後に慌てて修正するのではなく、今のうちにURL生成の前提をテストで固定しておくことが、最も安全な対応です。
コメント