REST API による CSV ファイルのアップロードと処理
CSV ファイルを file という名前のマルチパートフォームフィールドとして
POST /upload に送信し、インポートしたレコードを
GET /data から取得します。このチュートリアルでは Express と Multer でこれらのエンドポイントを構築し、csv-parse で CSV を検証済みの JSON レコードに変換します。インポートが成功すると以前のデータセットを置き換え、拒否された場合は以前のデータセットを維持します。
このサンプルでは、共有データセットを一つメモリに保存し、ローカルマシンでのみ接続を待ち受けます。小規模なインポートのデモなので、サーバーを再起動するとデータが消去されます。ログイン機能やユーザーごとのストレージはありません。
前提条件
Node.js 24.x または 26.x、Yarn 4.12.0 を利用できる Corepack、Bash 互換のターミナルを使用します。また、コマンドで --fail-with-body を使うため、cURL 7.76.0 以降が必要です。このサンプルは macOS 上で Node.js 24.21.0 と 26.8.2、Yarn 4.12.0、cURL 8.7.1 を使ってテストしました。
ここで使う CSV 形式では、ヘッダーが name,age の順に並び、データ行が少なくとも一つ必要です。名前は空白のみにできません。年齢は一桁から三桁の十進数字で、ゼロから 130 までの範囲にする必要があります。インポーターは値の前後の空白を削除し、年齢を JSON の数値に変換します。入力にはカンマ区切りの UTF-8 を使用します。UTF-8 のバイトオーダーマーク、引用符で囲まれたカンマや改行に対応しています。空行はスキップします。
Node.js と Express サーバーのセットアップ
新しい csv-upload-api フォルダーを作成したいディレクトリで、以下を実行します。サブシェルを使うため、現在のディレクトリは変わりません。そのフォルダーがすでに存在する場合は、パッケージのインストールやファイルの上書きをせずに停止します。セットアップをやり直す場合は、新しい場所を選んでください。
(
mkdir csv-upload-api &&
cd csv-upload-api &&
printf '{"name":"csv-upload-api","private":true,"packageManager":"yarn@4.12.0"}\n' > package.json &&
touch yarn.lock &&
corepack yarn config set nodeLinker node-modules &&
corepack yarn add --exact express@5.2.1 multer@2.4.0 csv-parse@7.0.2
)
空のロックファイルにより、別のプロジェクト内に作成した場合でも、独立した Yarn プロジェクトになります。解決済みの依存関係のバージョンを維持するため、生成された yarn.lock をサンプルと一緒に保存してください。Multer 2.4.0 には、アップロード中断時のディスククリーンアップに関する脆弱性の修正が含まれています。このサンプルを応用する際も、この依存関係に修正を適用し続けてください。
ファイルアップロード用エンドポイントの実装
新しい csv-upload-api ディレクトリ内に server.js を作成し、以下のコード全体を記述します。Multer は最大 5 MiB のファイルを一つ受け付け、追加のフォームフィールドは受け付けません。single('file') ミドルウェアが一時ファイルを書き込み、req.file として公開します。
const fs = require('node:fs')
const path = require('node:path')
const { pipeline } = require('node:stream/promises')
const { CsvError, parse } = require('csv-parse')
const express = require('express')
const multer = require('multer')
const app = express()
const port = Number(process.env.PORT || 3100)
const upload = multer({
dest: path.join(__dirname, 'uploads'),
limits: { fileSize: 5 * 1024 * 1024, files: 1, fields: 0, parts: 1 },
})
class InvalidCsv extends Error {}
let storedData = []
async function parseUpload(filePath) {
try {
const results = []
await pipeline(
fs.createReadStream(filePath),
parse({
bom: true,
skip_empty_lines: true,
max_record_size: 64 * 1024,
columns(header) {
if (header.length !== 2 || header[0] !== 'name' || header[1] !== 'age') {
throw new InvalidCsv('Expected the header name,age.')
}
return header
},
}),
async (rows) => {
for await (const row of rows) {
const name = row.name.trim()
const age = row.age.trim()
if (name === '' || !/^\d{1,3}$/.test(age) || Number(age) > 130) {
throw new InvalidCsv('Each row needs a name and an integer age from 0 to 130.')
}
if (results.length === 10000) {
throw new InvalidCsv('At most 10,000 records are allowed.')
}
results.push({ name, age: Number(age) })
}
},
)
if (results.length === 0) {
throw new InvalidCsv('Include at least one data row.')
}
return results
} finally {
await fs.promises.unlink(filePath)
}
}
app.post('/upload', upload.single('file'), async (req, res) => {
if (!req.file) {
return res.status(400).json({ error: 'Send a CSV file in the file field.' })
}
const results = await parseUpload(req.file.path)
storedData = results
res.json({ recordsStored: results.length })
})
app.get('/data', (req, res) => {
res.json(storedData)
})
// Express recognizes error middleware by its four arguments; register it after the routes.
app.use((error, req, res, next) => {
if (res.headersSent) return next(error)
if (error instanceof multer.MulterError) {
const tooLarge = error.code === 'LIMIT_FILE_SIZE'
return res.status(tooLarge ? 413 : 400).json({
error: tooLarge ? 'The file exceeds 5 MiB.' : 'Send one file field and no other fields.',
})
}
if (error instanceof InvalidCsv) {
return res.status(400).json({ error: error.message })
}
if (error instanceof CsvError) {
return res.status(400).json({ error: 'Invalid CSV syntax or record too large.' })
}
console.error('CSV import failed because of an unexpected server error.')
res.status(500).json({ error: 'Unable to import the file.' })
})
app.listen(port, '127.0.0.1', () => {
console.log(`CSV API listening on http://127.0.0.1:${port}`)
})
エンドポイントは、クライアントが指定したファイル名や MIME タイプにかかわらず、内容を検証します。これらの情報だけでは、ファイルに有効な CSV が含まれているとは判断できません。data.csv という名前のファイルでも、パーサーと行の検証を通過する必要があります。
CSV データの解析と保存
パーサーの columns コールバックは、レコードオブジェクトを作成する前にヘッダーを検証します。name,age との完全一致を必須とすることで、列の重複、欠落、想定外の列を拒否します。パーサーは行ごとの列数の不一致や閉じられていない引用符付きフィールドを拒否し、ループでは新しいデータセットに追加する前に値を検証します。
pipeline は、読み取り、解析、行の検証が完了するまで待機します。その後、finally ブロックが、解析に失敗した場合も含めて一時ファイルを削除します。その処理が終わって初めて、/upload が
storedData を置き換えます。Express 5 は非同期ルートの Promise の拒否を転送するため、エラーミドルウェアで処理できます。ファイルシステムの障害時には、パーサーのメッセージやローカルパスではなく、汎用的な 500 レスポンスを返します。
ファイルサイズの上限 5 MiB に加え、max_record_size がパーサーのレコードバッファーを制限し、ループが出力を 10,000 レコードまでに制限します。解析にはストリームを使いますが、完成したレコードはメモリに保持されます。置き換えの途中では、以前のデータセットと新しいレコードの両方が存在する場合があります。同時アップロードはそれぞれ独立して処理され、最後に正常終了したものが採用されます。
API のテスト
csv-upload-api があるディレクトリから、一つのターミナルでサーバーを起動します。
(cd csv-upload-api && node server.js)
サーバーを実行したまま、同じ親ディレクトリで別のターミナルを使います。このコマンドはプロジェクト内に data.csv を作成します。noclobber により、非対話形式で再実行した場合も既存ファイルの上書きを拒否します。
(
cd csv-upload-api &&
set -o noclobber &&
cat > data.csv <<'CSV'
name,age
"Doe, Jane",34
Tim,42
CSV
)
そのファイルをアップロードします。-F はマルチパートリクエストを構築します。file はサーバーのフィールド名と一致する必要があります。リクエストの Content-Type ヘッダーを自分で設定せず、マルチパートの境界値は cURL に設定させてください。
curl --fail-with-body --silent --show-error \
-F 'file=@csv-upload-api/data.csv;type=text/csv' http://127.0.0.1:3100/upload
レスポンスは {"recordsStored":2} です。保存されたレコードを取得します。
curl --fail-with-body --silent --show-error http://127.0.0.1:3100/data
[{"name":"Doe, Jane","age":34},{"name":"Tim","age":42}]
次に、年齢が欠けた行を送信します。このリクエストは標準入力から CSV を読み取るので、ローカルファイルの作成や置き換えは行いません。
curl --fail-with-body --silent --show-error --write-out '\nHTTP %{http_code}\n' \
-F 'file=@-;filename=invalid.csv;type=text/csv' http://127.0.0.1:3100/upload <<'CSV'
name,age
Tim
CSV
HTTP 400 と {"error":"Invalid CSV syntax or record too large."} が返ることを確認します。--fail-with-body により、cURL はコード 22 で終了します。この拒否は想定どおりの結果です。GET /data コマンドを再実行すると、Jane と Tim が残っているはずです。正常なアップロードを繰り返すと、重複を追加することなく、同じ二つのレコードでデータセットを置き換えます。
ほかにも、空のファイルやヘッダーだけの CSV で 400 が返ること、5 MiB を超えるファイルで 413 が返ることを確認するとよいでしょう。file パートの欠落、異なるフィールド名、複数のファイル、追加のテキストフィールドがある場合も 400 を返します。無効な CSV によるエラーはクライアントエラーとして扱い、想定外のストレージ障害では 500 を返します。
Postman では、POST と http://127.0.0.1:3100/upload を選択します。Body → form-data で file という名前のキーを一つ追加し、型を File に設定して data.csv を選択します。境界値を含むリクエストの Content-Type ヘッダーは Postman に生成させてください。終わったら Ctrl+C でサーバーを停止します。
本番環境での考慮事項
このエンドポイントを公開する前に認証を追加し、各データセットのインポートと読み取りの両方を認可してください。共有配列を永続ストレージに置き換え、トランザクションや段階的なインポートを使い、不正な行によってデータセットが一部だけ更新された状態にならないようにします。認証だけでは、ユーザー間でレコードを分離できません。
一時アップロードは、公開配信するディレクトリの外に保存してください。ここでのクリーンアップは通常のリクエスト障害やパーサーのエラーに対応しますが、プロセスがクラッシュするとファイルが残る場合があります。そのため、デプロイするサービスには、放置されたアップロードを削除するポリシーも必要です。リクエストのタイムアウト、レート制限、同時実行数の制限を適用してください。ファイルごとの上限だけでは、多数の同時リクエストによるメモリとディスクの合計使用量を制限できません。大規模なインポートでは通常、バックグラウンドジョブとインポート状況を返すエンドポイントが必要です。
