
# HTTP Client

HTTP Client の拡張機能は、IntelliJ IDEA の HTTP Client を Zed にもたらします。リクエストを `.http` や `.rest` ファイルに書き、ガターの ▶ ボタンで実行すると、応答が Zed のターミナルに表示されます。コードの中では、すべてのルートや HTTP クライアントの呼び出しが、それを既製のリクエストに変えるレンズを受け取ります。

ファイルの形式は IntelliJ IDEA、WebStorm、PhpStorm と互換性があり、VS Code の REST Client ともおおむね互換性があるので、既存の `.http` ファイルと `http-client.env.json` ファイルはそのまま動きます。

| | |
|---|---|
| 拡張機能の ID | `http-client` |
| バージョン | `0.3.1` |
| 言語 | HTTP (`.http`、`.rest`)。加えて Dart、Java、Kotlin、JavaScript、TypeScript、TSX、Python、Go、Rust、PHP、Ruby、C# でのリクエストの生成 |
| ランナー | 拡張機能が自分でインストールするネイティブのバイナリー `zed-http` |
| プラットフォーム | macOS と Linux。Windows でも動くはずですが未テスト |
| ソース | zed_editor_extensions リポジトリの [http-client-extension](https://github.com/farum-azula/zed_editor_extensions/tree/main/http-client-extension) |

## 提供するもの

- `.http` と `.rest` ファイルのための **HTTP 言語**: メソッド、URL、ヘッダー、`{{...}}` 変数、HTTP のバージョン、`###` の区切りのハイライト。ボディの中の JSON、XML、GraphQL のハイライト。アウトラインパネル (`Cmd-Shift-O`) のファイルのリクエスト。`#` と `//` のコメント (`Cmd-/`)。
- すべてのリクエストのガターの **▶ 実行ボタン** と、一つまたはすべてのリクエストを実行するタスク。
- **変数と環境**: ファイルの変数、private ファイル付きの `http-client.env.json`、`$shared`、`{{$uuid}}` のような動的な変数。
- ファイルの最初の行の上と、リクエストごとの **環境の切り替え**。
- すべての `{{variable}}` の **定義へ移動とホバー**。
- **リクエストのチェーン**: 名前付きのリクエストと、以前の応答のボディ、ヘッダー、ステータスへの参照。
- **ファイルからのボディ**、マルチパート、応答のファイルへの保存、Basic 認証の省略形、リダイレクトなし。
- 10 の言語にわたる 50 のフレームワークと HTTP クライアントでの **コードからのリクエストの生成**。
- スクリプト、CI、AI エージェントのための **`zed-http` コマンドラインツール**。

## 見た目

`api.http` を作ります。

```http
@baseUrl = https://httpbin.org

### Get data
GET {{baseUrl}}/get?client=zed
Accept: application/json

### Create a record
POST {{baseUrl}}/post
Content-Type: application/json

{
  "id": "{{$uuid}}",
  "name": "Zed"
}
```

各 `GET` と `POST` の行の横のガターに ▶ が現れます。`GET` の横のものをクリックすると、`HTTP: GET {{baseUrl}}/get?client=zed` という名前のターミナルのタブが開き、次のように表示されます。

```text
GET https://httpbin.org/get?client=zed
Accept: application/json

HTTP/1.1 200 OK  413 ms · 250 B
access-control-allow-origin: *
content-length: 250
content-type: application/json
date: Sat, 07 Nov 2026 19:05:38 GMT

{
  "args": {
    "client": "zed"
  },
  "headers": {
    "Accept": "application/json",
    "Host": "httpbin.org"
  },
  "method": "GET",
  "url": "https://httpbin.org/get?client=zed"
}

saved: ./.zed-http/line-3.json
```

環境のファイルが見つかった場合は、`environment: dev` の行が先頭に来ます。

ステータスは、2xx では緑、3xx では黄、4xx と 5xx では赤です。JSON は整形され、バイナリーのボディはそのサイズと種類だけが表示されます。`saved:` のパスはクリックでき、ハイライトと検索付きで Zed で応答を開きます。

`{{baseUrl}}` にホバーすると、解決された値とその出どころが表示されます。

```text
baseUrl · environment `dev`
https://httpbin.org
```

ファイルの最初の行の上には、ファイル自身のものを先頭に、環境を示すレンズの行があります。

```text
env: prod | dev | staging
```

## リクエストを実行する

| 方法 | 実行されるもの |
|---|---|
| メソッドの横のガターの ▶ | このリクエスト |
| `task: spawn` → `HTTP: GET …` | カーソルの下のリクエスト。`# @name` があればその名前が付く |
| `task: spawn` → `HTTP: run all requests in …` | ファイルのすべてのリクエストを順に |
| `task: rerun` | 最後の実行をもう一度 |
| キーバインド ([キーバインド](None#キーバインド) を参照) | カーソルに最も近いリクエスト |

タスクとそのターミナルのタブには、リクエストの `# @name` (`HTTP: get-todos-by-id`)、またはそのメソッドと URL の名前が付きます。

## .http ファイルの形式

```http
### Optional title
# @name requestName
METHOD URL [HTTP/version]
Header: value
Header: value

request body
```

- リクエストは `###` で始まる行で区切られます。`###` の後のテキストはタイトルです。
- メソッドは省略可能です。`https://example.com` だけの行は `GET` を意味します。サポートされるメソッド: `GET`、`POST`、`PUT`、`PATCH`、`DELETE`、`HEAD`、`OPTIONS`、`TRACE`、`CONNECT`。
- スキームのない URL には `http://` が付きます。行末のバージョンは許可され、無視されます。
- ヘッダーはリクエストの行に続き、ボディは空行の後に来ます。
- URL の後のインデントされた行はそれを継続し、空白なしでつながれます (`?q=zed` の次に `&limit=10`)。
- `#` と `//` はコメントを始めます。

### ディレクティブ

| ディレクティブ | 意味 |
|---|---|
| `# @name login` | リクエストの名前: `--name`、応答の参照、タスクのタイトルのため |
| `# @env prod` | 環境: 最初の `###` の上ならファイル全体の、その下なら一つのリクエストの |
| `# @no-redirect` | 3xx のリダイレクトをたどらない |
| `# @no-log` | 応答を保存しない。以後の実行はそれを参照できない。生成されたリクエストはこれを持つ |

## 変数

変数は、URL、ヘッダー、ボディ、ファイルパスの中で `{{name}}` と書きます。波括弧の中の空白は許可され、値は他の変数を含められます。

```http
@host = api.example.com
@baseUrl = https://{{host}}/v1

GET {{baseUrl}}/users
```

ファイルの変数はファイル全体に適用され、環境の値を上書きします。

### 動的な変数

| 変数 | 結果 |
|---|---|
| `{{$uuid}}`、`{{$random.uuid}}` | UUID v4 |
| `{{$timestamp}}` | 秒単位の Unix 時間 |
| `{{$isoTimestamp}}` | `2026-10-16T11:01:53.123Z` のような ISO 8601 の UTC 時刻 |
| `{{$randomInt}}` | 0 から 999 の整数 |
| `{{$randomInt 1 100}}`、`{{$random.integer 1 100}}` | `[1, 100)` の整数 |
| `{{$random.float}}` | 0 と 1 の間の浮動小数点数 |
| `{{$random.alphabetic 8}}` | 8 個のランダムな英字 |
| `{{$random.alphanumeric 12}}` | 12 個のランダムな英数字 |
| `{{$random.hexadecimal 16}}` | 16 個の 16 進数の文字 |
| `{{$processEnv.TOKEN}}`、`{{$env.TOKEN}}` | OS の環境変数 `TOKEN` |

使うたびに新しい値が生成されます。変数は次の順で検索されます。動的な変数、ファイルの変数、選択された環境 (public より private のファイル)、`$shared` ブロック、そして保存された応答への参照です。未知の変数はエラーで、リクエストは送られません。

## 環境

`http-client.env.json` はプロジェクトとともにコミットします。

```json
{
  "$shared": { "apiVersion": "v1" },
  "dev": { "baseUrl": "http://localhost:8080" },
  "prod": { "baseUrl": "https://api.example.com" }
}
```

`http-client.private.env.json` は秘密情報を保持し、`.gitignore` に入れるべきものです。

```json
{
  "dev": { "token": "dev-secret" },
  "prod": { "token": "prod-secret" }
}
```

private ファイルは public のものの上にマージされます。ファイルは `.http` ファイルのフォルダーとその `.zed/http/` で探され、次に最初に一致するまでツリーを上へたどります。

**環境を選ぶ。** 最初の行の上のレンズの行で一つをクリックすると、ファイルに `# @env` が書き込まれます。リクエストは独自の環境を持てます。カーソルをそれに置き、`Cmd-.` を押して **HTTP: choose an environment for this request** を選びます。すると、そのレンズの行は再びそれを取り除くための `from file` を提供します。レンズには Zed の設定で `"code_lens": "on"` が必要です。それがなければ、`# @env` の行を入力してください。

環境は優先順位で選ばれます。

1. CLI の `--env prod` フラグ。
2. その `###` の下にある、リクエスト自身の `# @env`。
3. 最初の `###` の上にある、ファイルの `# @env`。
4. `HTTP_CLIENT_ENV` 変数。たとえば `"terminal": { "env": { "HTTP_CLIENT_ENV": "prod" } }` の中で。
5. あれば `dev`、`local`、`development`。
6. ファイルの最初の環境。

定義されていない環境は、何かが送られる前に実行を止め、レンズで `(not defined)` と示されます。

## 定義へ移動

変数の上で `Cmd` クリックまたは `F12`:

| カーソルの下 | 移動先 |
|---|---|
| `@token = ...` で宣言された `{{token}}` | `@token` の行 |
| 環境からの `{{baseUrl}}` | `http-client.env.json` または private ファイルの `"baseUrl"` キー |
| `{{login.response.body.token}}` | `# @name login` |
| `{{$uuid}}` とその他の動的な変数 | どこにも移動しない |

変数が public と private の両方のファイルにある場合、Zed は両方を列挙します。応答の参照のホバーは保存された値を表示するか、リクエストがまだ実行されていないことを伝えます。動的な変数のホバーは値のサンプルを表示します。

## リクエストのチェーン

名前付きのリクエストの応答は保存され、以後のリクエストで使えます。

```http
### Login
# @name login
POST {{baseUrl}}/auth/login
Content-Type: application/json

{ "user": "admin", "password": "{{password}}" }

### Profile
GET {{baseUrl}}/me
Authorization: Bearer {{login.response.body.accessToken}}
```

| 式 | 値 |
|---|---|
| `{{login.response.body}}` | ボディ全体 |
| `{{login.response.body.data.token}}` | パスによる JSON のフィールド |
| `{{login.response.body.$.data.token}}` | 同上、JSONPath の形式 |
| `{{login.response.body.items[0].id}}` | 配列の要素 |
| `{{login.response.headers.Location}}` | ヘッダー。大文字小文字を区別しない |
| `{{login.response.status}}` | ステータスコード |

応答は `.http` ファイルの隣の `.zed-http/responses.json` に保存され、再起動後も残ります。`login` を一度実行すれば、他のリクエストを一つずつ実行できます。`@name` のないリクエストは `line-<number>` として保存されます。

## ボディと応答

| 構文 | 効果 |
|---|---|
| 空行の後のボディ | 次の `###` まで、そのまま送られる。末尾の空行は取り除かれる |
| ボディとしての `< ./payloads/item.json` | ファイルが変数の置換なしにバイト列として送られる |
| マルチパートのボディの中の `< ./report.txt` | ファイルのテキストで置き換えられる |
| `Authorization: Basic user password` | 自動で Base64 エンコードされる (`user:password` も) |
| リクエストの後の `>> ./out/report.csv` | 応答を保存する。存在すれば `report-1.csv`、`report-2.csv` など |
| `>>! ./out/report.csv` | 応答を保存し、ファイルを上書きする |

すべての応答は、`Content-Type` で選ばれた拡張子で、`.zed-http/<name or line-N>.<ext>` にも保存されます。`.gitignore` に追加してください。

```text
.zed-http/
http-client.private.env.json
```

## コードからリクエストを生成する

コードの中のすべてのルートや HTTP クライアントの呼び出しは、行の上に **🌐 Generate .http request** レンズを受け取ります。一回のクリックで、完全なリクエストが `.zed/http/endpoints/<source file>.http` (`server.ts` は `server.ts.http` になります) に追加され、それが開きます。リクエストが存在すると、レンズは **🔗 Open** とファイル名 (`🔗 Open server.ts.http` など) になります。同じアクションは `Cmd-.` のメニューにもあります。Zed ではコードレンズはデフォルトで無効なので、有効にしてください。

```json
{ "code_lens": "on" }
```

`"menu"` では、レンズは代わりに `Cmd-.` のメニューに現れます。ここではガターの ▶ は不可能です。拡張機能がガターのボタンを追加できるのは、自分で定義する言語だけだからです。

リクエストは、同じファイルのハンドラーとモデルのクラスから埋められます。パス変数は、先頭に `@id = 1` を置いた `{{id}}` になります。クエリパラメーター、ヘッダー、型に基づくプレースホルダー (`""`、`0`、`false`、`[]`、入れ子のオブジェクト) を持つ JSON のボディが追加され、ハンドラーが認証を必要とする場合は `Authorization: Bearer {{token}}` が追加されます。Spring for Dart のコントローラーの場合:

```dart
@RestController()
@RequestMapping('/api/books')
class BookController {
  @GetMapping('/{isbn}')
  Future<Book> find(@PathVariable() String isbn) => books.find(isbn);

  @PostMapping()
  Future<ResponseEntity<Book>> create(
    @RequestHeader('X-Request-Id') String requestId,
    @RequestBody() @Valid() NewBook book,
  ) async => ...
}

class NewBook {
  const NewBook({required this.isbn, required this.title, this.stock = 0});

  final String isbn;
  final String title;
  final int stock;
}
```

`@GetMapping` と `@PostMapping` のレンズは、`.zed/http/endpoints/book_controller.dart.http` に次のものを追加します。

```http
### get-api-books-by-isbn
# @name get-api-books-by-isbn
# @no-log
@isbn = 1
GET {{baseUrl}}/api/books/{{isbn}}
Accept: application/json

### post-api-books
# @name post-api-books
# @no-log
@xRequestId = value
POST {{baseUrl}}/api/books
Accept: application/json
X-Request-Id: {{xRequestId}}
Content-Type: application/json

{
  "isbn": "",
  "title": "",
  "stock": 0
}
```

**サーバーのアドレス。** Spring のアプリケーション (Java や Kotlin の Spring Boot、または Spring for Dart) では、拡張機能は `application.yml`、`application.yaml`、`application.properties` (Spring for Dart では `lib/resources/` の中) から、`server.port`、`server.servlet.context-path`、`server.address`、TLS の設定を読みます。最初に生成されたリクエストが、そのアドレスを持つ `.zed/http/http-client.env.json` を作ります (`"baseUrl": "http://localhost:9090/shop"` など)。自分で設定した `baseUrl` が変更されることはありません。

**クライアントはクライアントの行き先へ。** Feign クライアント (`@FeignClient`、Java と Dart) は、同じ設定から `${...}` プレースホルダーを解決した `url` を使います。解決できないものは、`{{catalogUrl}}` のように、プロパティにちなんだ名前の変数になります。

`http.post(_endpoint, ...)` のように **変数に保持された URL** も見つけられます。リクエストは、変数に代入された URL、それを読む環境変数 (`{{GROQ_URL}}`)、または変数名が URL を示す場合はその名前 (`{{apiUrl}}`) を使います。

複数の文やファイルにわたって組み立てられる URL は見つけられず、他のファイルで定義されたモデルは解決されません。その場合、ボディは `{}` になります。

### サポートされるフレームワーク

フレームワークは、ファイルがそのインポートのいずれかを持つ場合にだけ、そのファイルで有効になるので、同じ言語のフレームワークが干渉することはありません。

| 言語 | フレームワークとクライアント |
|---|---|
| Dart と Flutter | Spring Web for Dart (`spring_boot_starter_web`)、Feign for Dart (`spring_boot_starter_feign`)、Dio、`package:http`、retrofit.dart、Chopper、shelf_router |
| Java | Spring Web (MVC、WebFlux、OpenFeign)、JAX-RS (Quarkus、Jakarta EE、Helidon、Dropwizard)、Micronaut、Retrofit、OpenFeign |
| Kotlin | Spring Web、Ktor サーバー、Ktor クライアント、Retrofit、JAX-RS (Quarkus) |
| TypeScript と JavaScript | Express、Fastify、Hono、Koa router、NestJS、Axios、Angular HttpClient、fetch |
| Python | FastAPI、Flask、Django URLconf、requests / httpx / aiohttp |
| Go | gorilla/mux、net/http、Gin、Echo、chi、Fiber |
| Rust | axum、actix-web、Rocket、reqwest |
| PHP | Laravel、Symfony、Slim、Guzzle |
| Ruby | Rails routes、Sinatra、Faraday / HTTParty |
| C# | ASP.NET Core のコントローラー、ASP.NET Core の minimal API、Refit、HttpClient |

カタログは [frameworks.json](https://github.com/farum-azula/zed_editor_extensions/blob/main/http-client-extension/frameworks.json) です。正規表現ではなく、型付きのプレースホルダーを持つソースコードとして書かれたパターンです。プロジェクトは `.zed/http/frameworks.json` で独自のフレームワークを追加でき、それは組み込みのカタログにマージされ、保存時に拾われます。

```json
{
  "$schema": "https://raw.githubusercontent.com/farum-azula/zed_editor_extensions/main/http-client-extension/frameworks.schema.json",
  "languages": {
    "dart": {
      "frameworks": {
        "my-api-client": {
          "name": "Our ApiClient",
          "imports": ["package:my_app/api_client.dart"],
          "routes": ["api.call(\"{method}\", \"{route}\""],
          "body": ["api.call(...data: {keys}"]
        }
      }
    }
  }
}
```

プロジェクトのルートでの `zed-http frameworks` は、マージされたカタログをチェックして表示します。[examples/code](https://github.com/farum-azula/zed_editor_extensions/tree/main/http-client-extension/examples/code) フォルダーには、フレームワークごとに一つの実行可能なファイルがあります。

## 新しいエンドポイント

`http: new endpoint` タスクは、ターミナルでメソッド、URL、名前を尋ね、`.zed/http/endpoints/<name>.http` を作り、それを開きます (`zed` コマンドが `PATH` にある場合)。環境がまだなければ、`dev` プロファイルを持つ `.zed/http/http-client.env.json` も作ります。拡張機能のタスクは `.http` ファイルが開いている間だけ見えます。これをどこでも使えるようにするには、`~/.config/zed/tasks.json` に追加します。

```json
[
  {
    "label": "http: new endpoint",
    "command": "zed-http",
    "args": ["new", "\"$ZED_WORKTREE_ROOT\""],
    "use_new_terminal": true,
    "reveal": "always",
    "hide": "on_success"
  }
]
```

## zed-http コマンド

ランナーは、ターミナルで、スクリプトで、CI で、単独で動きます。

```text
zed-http run <file.http> [--line N | --name NAME | --all] [--env ENV] [--raw] [--timeout SECS]
zed-http list <file.http>
zed-http envs <file.http>
zed-http new [ROOT] [--name NAME] [--method METHOD] [--url URL] [--from FILE:LINE] [--no-open]
zed-http detect <file> [--line N]
zed-http frameworks [ROOT]
zed-http lsp
```

| コマンドまたはフラグ | 効果 |
|---|---|
| `run` | リクエストを実行する |
| `list` | リクエストを列挙する: 行、メソッド、URL、名前 |
| `envs` | 環境を列挙する |
| `new` | `ROOT/.zed/http/endpoints/<name>.http` を作る。`--from FILE:LINE` はコードからメソッドと URL を取る。`--no-open` はそれを開かない |
| `detect` | コードの中のエンドポイントを見つける: 行、メソッド、URL、フレームワークをタブ区切りで |
| `frameworks` | サポートされるフレームワークを表示し、`ROOT/.zed/http/frameworks.json` をチェックする |
| `lsp` | Zed が起動する言語サーバー |
| `-l`、`--line N` | 行 `N` を含むリクエスト |
| `-n`、`--name NAME` | `@name` またはタイトルによるリクエスト |
| `-a`、`--all` | すべてのリクエストを順に |
| `-e`、`--env ENV` | 環境 |
| `--raw` | JSON の整形なし |
| `--timeout SECS` | リクエストのタイムアウト。デフォルトは 60 秒 |

終了コードは、すべてのリクエストが 400 未満のステータスを返した場合は `0`、一つが 4xx や 5xx を返したり失敗したりした場合は `1`、引数、ファイル、変数、環境のエラーでは `2` です。そのため、`zed-http run smoke.http --all --env staging` は CI のチェックとして使えます。

```sh
$ zed-http detect lib/api/auth_api.dart
12	POST	{{baseUrl}}/auth/login	dart/dio
```

## キーバインド

エディターにフォーカスを保ったまま、`Cmd-Enter` でカーソルの下のリクエストを実行するには、キーマップ (`zed: open keymap`) に追加します。

```json
[
  {
    "context": "Editor && extension == http",
    "bindings": {
      "cmd-enter": ["editor::SpawnNearestTask", { "reveal": "no_focus" }]
    }
  }
]
```

## ランナーのインストールのされ方

拡張機能は次の順で `zed-http` を見つけます。

1. すでに `PATH` 上にある `zed-http`。自分のインストールが常に優先されます。
2. 以前にインストールしたコピー。Zed の拡張機能の作業ディレクトリの下の、そのフォルダーにあります。
3. リポジトリの [リリース](https://github.com/farum-azula/zed_editor_extensions/releases) からダウンロードした、このプラットフォーム向けのリリースビルド (macOS と Linux、Intel と ARM)。
4. 拡張機能自身の `cli/` フォルダーからの `cargo install` によるビルド。リポジトリからクローンした開発用の拡張機能では、これが通常のケースです。その場合、最初の起動にはランナーのリリースビルドと同じだけの時間がかかります。

その間、Zed はサーバーをインストール中として表示します。サーバーは `~/.zed-http/bin` に自分のコピーを保持し、`PATH` に `zed-http` がない場合、▶ ボタンはそこを探します。CLI として使うためにランナーを手でインストールするには:

```sh
cd zed_editor_extensions/http-client-extension
cargo install --path cli
```

## 制限

- JavaScript の応答のハンドラー (`> {% ... %}`) とリクエスト前のスクリプトはスキップされます。リクエスト間でデータを渡すには `{{name.response...}}` を使ってください。
- 応答は独自のパネルではなくターミナルに表示されます。Zed の拡張機能はパネルを追加できません。
- WebSocket、gRPC、GraphQL のサブスクリプション、HTTP/2 固有の機能はありません。GraphQL のクエリは JSON の `POST` として送ってください。
- リクエスト間の Cookie の保存はありません。
- `$processEnv` の値は Zed のターミナルの環境変数から来ます。

## トラブルシューティング

**ガターに ▶ がない。** 右下の言語が **HTTP** であることと、`"gutter": { "runnables": true }` が無効にされていないことを確認してください。▶ はあるのに実行すると `zed-http: command not found` と報告される場合、このウィンドウではサーバーがまだ起動していません。`.http` ファイルを開き、ステータスバーに **zed-http** が表示されるのを待ってから、もう一度実行してください。

**▶ はあるが、`HTTP: …` タスクが提供されない。** 拡張機能の `languages/http/tasks.json` をプロジェクトの `.zed/tasks.json` にコピーしてください。

**変数の上で `Cmd` クリックしても何も起きない。** `editor: restart language server` を実行し、`dev: open language server logs` を確認してください。

**cargo でインストールしたランナーで `zed-http: command not found`。** `~/.cargo/bin` が、Zed が起動するシェルの `PATH` にありません。シェルのプロファイルに追加し、Zed を再起動してください。

**`unknown variable {{baseUrl}}`。** `http-client.env.json` が見つからないか、環境にその変数がありません。`zed-http envs file.http` を実行し、出力の先頭の `environment:` の行を確認してください。

**`no stored response for request 'login'`。** まず `# @name login` を持つリクエストを実行してください。

**自己署名証明書での TLS のエラー。** システムのルート証明書が使われます。自分の CA をシステムのストアに追加してください。

## リンク

- [拡張機能のソース](https://github.com/farum-azula/zed_editor_extensions/tree/main/http-client-extension)
- [リクエストの例](https://github.com/farum-azula/zed_editor_extensions/blob/main/http-client-extension/examples/requests.http)
- [ランナーのバイナリーを含むリリース](https://github.com/farum-azula/zed_editor_extensions/releases)
- [インストール](installation.md)
