ここから実際に手を動かします。そして最初にやることは、コードを書くことではありません。
前回: 作らないものリストを先に書く — 個人開発の題材選び 作業場所はVMの中(Ubuntu Server)です。Node.js と MySQL が入っていて、
~/serverで Express と ORMとマイグレーションの基本|スキーマ変更を手で打たない仕組み が動いた経験がある状態から始めます。~/serverは今回いっさい開きません。
前回までで、作るものが決まりました。hitokoto(ひとこと) — 読んだ本と、そこから引いた一文を残すアプリです。
新しいフォルダを作ります。 ~/server の続きにはしません。
理由を先に書きます。 ~/server は、サーバーとは何かからREST、認証まで、試したことが全部積み上がった場所です。動かなくなった実験も、途中でやめたコードも、消し忘れたテーブルも入っています。
あれは教材です。作品ではありません。
混ぜると、こうなります。
| 混ぜると起きること | なぜ困るか |
|---|---|
| どこまでが作品か分からなくなる | 人に見せるとき、「この部分は関係ありません」と言い訳することになる |
| 消していいものが判断できない | 練習で作った tasks テーブルを消したら、作品が動かなくなる、が起こる |
git init する範囲が決まらない | 履歴の1行目から、練習の残骸が混ざる |
| 再現できない | 「動いています」と言えても、別のVMに持っていくと動かない。何が要るのか分からないため |
作品は、まっさらな場所から作ります。 これは几帳面さの話ではなく、「動かせる」ではなく「仕組みが分かる」を守るための話です。何が要って何が要らないかは、空の状態から1つずつ入れたときにしか分かりません。
対象レベル: 中級 / 区分: 必修
この記事でわかること
- 練習用のフォルダの続きに作品を作ってはいけないこと。何が必要かは、空から始めたときにしか分からないこと
- テーブルは
CREATE TABLEで作らないこと。先にマイグレーションという「変更の履歴」を作り、そこからテーブルが生まれるという順番 - 外部キーの
ON DELETEは「どれが正しい」ではなく「消えていいものかどうか」で選ぶこと。同じアプリの中で違う指定が混ざるのが普通だということ - 全部書いてから動かすと、どこが壊れているのか永久に分からなくなること。最初に通すのは2本だけでいいこと
- 登録画面は、作品に必ず要るものではないこと。一人で使うなら、利用者は
seedで作れば足りること - 入力の検証は「あるかないか」ではなく「エラーの形が1つに揃っているか」が本体だということ
- ログイン不要のAPIは、
ifで分岐させず、URLごと別の道にしたほうが事故らないこと - 画面が1枚も無くても、APIは完成させられること。
curlが通れば、そこは終わっている
この記事でやること
~/hitokotoを新しく作り、.envとデータベースの利用者をコードより先に用意する- マイグレーションを3枚書いて
users/books/quotesを作る。外部キーとON DELETEを用途で選び分ける - APIのURLを、表にして先に全部決める
POST /api/booksとGET /api/booksの2本だけを書いて通す。動いてから次を足す- 管理者1人を
seedで作り、書き込みだけログインを要求する - 入力の検証とエラーの形を揃え、公開用のAPIを別の道に分ける
curlで全部叩いて確かめ、systemdで常駐させる
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| マイグレーション | データベースの変更を1件ずつ記録したファイル。 実行すると表ができ、巻き戻すと消える |
| シード(seed) | 最初から入っていてほしいデータを入れる仕組み。 この記事では管理者を1人だけ作る |
| エンドポイント | APIの入口1つ。GET /api/books のようなメソッドとURLの組み合わせ |
| バリデーション | 送られてきた値が使える形か確かめること。 日本語では「検証」 |
ON DELETE | 参照先が消えたとき、参照している側をどうするかの指定 |
CASCADE | 一緒に消す。 親が消えたら子も消える |
RESTRICT | 消させない。 子がいる間は親を削除できない |
| ミドルウェア | Express で、本処理の前に必ず通る関数。 ログイン確認などをここに置く |
seed:run | シードを実際に流すコマンド |
この記事のコードは、いままで書いたものより長くなります。 一気に読まないでください。 ⑤の「2本だけ通す」まで来たら、そこで一度手を止めて
curlを打つのが、この記事のいちばん大事な使い方です。
① 場所を作る
入れるものを、理由と一緒に並べます。
| パッケージ | 何のため |
|---|---|
express | HTTPを受ける。APIの回で生のNodeから乗り換えたもの |
knex | マイグレーションとSQLの組み立て |
mysql2 | Knex が MySQL と話すためのドライバ |
express-session | ログイン状態を覚える |
express-mysql-session | その記憶をメモリではなくMySQLに置く |
bcryptjs | パスワードを戻せない形にする |
bcryptではなくbcryptjsです。 理由はパスワード保存の回に書いたとおりで、bcryptはビルド済みの部品が使えない環境(ビルド済みが用意されていない Node の版など)では入れるときにコンパイルが走り、素のUbuntu Serverにはそのための道具が入っていません。
.gitignore を、コードを1行も書く前に作ります。
これを後回しにすると、
.envが履歴に入ったまま気づかない、が起きます。 一度コミットされた秘密は、そのファイルを消しても履歴には残ります。 Gitの導入の回で触れた話が、ここで効いてきます。
② .env を最初に作る
コードより先に、置き場所と鍵を決めます。 「あとで環境変数に出す」は、ほぼ確実にやりません。
まずデータベースと、利用者を2人作ります。
CREATE DATABASE hitokoto CHARACTER SET utf8mb4;
CREATE USER 'hitokoto_app'@'localhost' IDENTIFIED BY 'ここにパスワード1';
GRANT SELECT, INSERT, UPDATE, DELETE ON hitokoto.* TO 'hitokoto_app'@'localhost';
CREATE USER 'hitokoto_migrator'@'localhost' IDENTIFIED BY 'ここにパスワード2';
GRANT ALL PRIVILEGES ON hitokoto.* TO 'hitokoto_migrator'@'localhost';
FLUSH PRIVILEGES;
EXIT;
なぜ利用者を2人に分けるのか。 アプリが動いている間、
DROP TABLEができる必要はありません。 ORMとマイグレーションの回でやったのと同じ考え方です。hitokoto_appは表を作れません。 だから、アプリのバグや外からの攻撃で表が消えることが構造的に起きません。表を作り替えるのは、人が意識して打つマイグレーションのときだけです。
パスワードを作ります。
3つ出た文字列を、こう振り分けます。
DB_HOST=127.0.0.1
DB_USER=hitokoto_app
DB_PASSWORD=(1つ目)
DB_NAME=hitokoto
SESSION_SECRET=(3つ目)
PORT=3001
DB_HOST=127.0.0.1
DB_USER=hitokoto_migrator
DB_PASSWORD=(2つ目)
DB_NAME=hitokoto
ADMIN_EMAIL=あなたのメールアドレス
ADMIN_PASSWORD=ログインに使うパスワード
PORT=3001にしています。~/serverの練習用が3000で動いている可能性があるためです。 同じポートで2つは動きません(APIの回で出たEADDRINUSE)。作品には作品のポートを与えます。
knexfile.js を書きます。
module.exports = {
development: {
client: "mysql2",
connection: {
host: process.env.DB_HOST,
user: process.env.DB_USER,
password: process.env.DB_PASSWORD,
database: process.env.DB_NAME,
dateStrings: true,
},
migrations: { directory: "./migrations" },
seeds: { directory: "./seeds" },
},
};
dateStrings: trueを入れています。 これが無いと、finished_on(読了日)が JavaScriptのDateになって、時差のぶんだけ1日ずれます。 「日付だけ」を扱うときに毎回踏む場所です。時刻を持たない列は、文字列のまま受け取ったほうが安全です。
③ マイグレーションから書く
ここが、練習と作品のいちばん大きな違いです。
練習では CREATE TABLE を直接打ちました。動きます。 でも、こうなります。
直接 CREATE TABLE を打つと | 起きること |
|---|---|
| どんな表があるか、コードを読んでも分からない | データベースを見ないと分からない。他人に渡せない |
| 別のVMに持っていくと空 | 「動かすには、まずこのSQLを打ってください」という手順書が必要になる |
| 列を足したとき、何を足したか残らない | 半年後の自分が読めない |
マイグレーションは、表を作る道具ではありません。「表がこうなった理由」を残す道具です。
順番が逆転しているように感じます。 表が先にあって、それを記録するのではなく、記録を書いたら表ができる。 この向きに慣れると、データベースがコードの一部になります。
3枚に分ける
npx knexではなく、この長い形で打ちます。npxを通すと--env-fileが届かず、Access denied for user ''@'localhost'になります。前回踏んだところです。
なぜ3枚に分けるのか。 1枚にまとめても動きます。ただ、巻き戻す単位が変わります。
| 分け方 | 巻き戻すと |
|---|---|
| 1枚にまとめる | 全部消える。 セッション表まで消えてログアウトする |
| 3枚に分ける | quotes の設計だけやり直す、ができる |
「あとで直しそうなところ」を、別のファイルにします。
1枚目 — users
migrations/ にできたファイル(20260914..._001_users.js のような名前)を開きます。
exports.up = async function (knex) {
await knex.schema.createTable("users", (t) => {
t.increments("id").primary();
t.string("email", 255).notNullable().unique();
t.string("password_hash", 255).notNullable();
t.string("display_name", 100).notNullable();
t.timestamp("created_at").notNullable().defaultTo(knex.fn.now());
});
};
exports.down = async function (knex) {
await knex.schema.dropTableIfExists("users");
};
password_hashという名前にしています。passwordにしません。 列の名前は、後から読む人へのメッセージです。passwordと書いてあると、いつか誰かが平文を入れます。
2枚目 — books と quotes
exports.up = async function (knex) {
await knex.schema.createTable("books", (t) => {
t.increments("id").primary();
t.integer("user_id").unsigned().notNullable();
t.string("title", 200).notNullable();
t.string("author", 200).nullable();
t.date("finished_on").nullable();
t.timestamp("created_at").notNullable().defaultTo(knex.fn.now());
t.foreign("user_id").references("users.id").onDelete("RESTRICT");
t.index(["user_id"]);
});
await knex.schema.createTable("quotes", (t) => {
t.increments("id").primary();
t.integer("book_id").unsigned().notNullable();
t.text("body").notNullable();
t.integer("page").unsigned().nullable();
t.boolean("is_public").notNullable().defaultTo(false);
t.timestamp("created_at").notNullable().defaultTo(knex.fn.now());
t.foreign("book_id").references("books.id").onDelete("CASCADE");
t.index(["book_id"]);
t.index(["is_public", "created_at"]);
});
};
exports.down = async function (knex) {
await knex.schema.dropTableIfExists("quotes");
await knex.schema.dropTableIfExists("books");
};
ON DELETE を2種類使い分けている
これが、この回で正規化の回を回収するところです。
| 外部キー | 指定 | 意味 | なぜそうしたか |
|---|---|---|---|
books.user_id → users.id | RESTRICT | 本が1冊でもある人は消せない | 利用者を消したら本が全部消える、は取り返しがつかない。先に本を消せ、と機械に言わせる |
quotes.book_id → books.id | CASCADE | 本を消すと、その本の引用も消える | 本の無い引用に意味が無い。残しても誰も読めない孤児になる |
「どちらが正しいか」ではありません。 同じアプリの中で違う指定が混ざるのが普通です。 判断は1行で言えます。「親が消えたとき、この子は単独で意味を持つか?」 持つなら
RESTRICT(勝手に消すな)、持たないならCASCADE(一緒に消せ)。
down の順番にも意味があります。 quotes を先に消しています。逆にすると、books を参照している行が残っているので拒否されます。 これは失敗ではなく、外部キーが仕事をしている証拠です。
3枚目 — sessions
express-mysql-session は、表が無ければ自分で作ろうとします。でも hitokoto_app に CREATE 権限がありません。 だから、こちらで作っておきます。
exports.up = async function (knex) {
await knex.schema.createTable("sessions", (t) => {
t.string("session_id", 128).primary();
t.integer("expires").unsigned().notNullable();
t.text("data");
});
};
exports.down = async function (knex) {
await knex.schema.dropTableIfExists("sessions");
};
列の名前は
express-mysql-sessionが決めています。 ここだけは自由に付けられません。ライブラリが読みに来る名前だからです。
流す
[スクリーンショット: 01_migrate_status.png] migrate:status を実行して、3枚とも Completed と出ている画面を撮ってください。
確かめます。
+--------------------+
| Tables_in_hitokoto |
+--------------------+
| books |
| knex_migrations |
| knex_migrations_lock |
| quotes |
| sessions |
| users |
+--------------------+
knex_migrations は、Knex が「どこまで流したか」を覚えている表です。 ここを手で書き換えると迷子になります。触りません。
外部キーが本当に効いているか、1回だけ試します。
ERROR 1452 (23000): Cannot add or update a child row: a foreign key constraint fails
この失敗が見たかったものです。 存在しない利用者の本は、そもそも入れられません。
④ APIのURLを、先に表で決める
コードを書く前に、URLを全部決めます。
理由は、後から変えるのがいちばん高いからです。URLを変えると、画面側の呼び出しも、ブックマークも、公開ページのリンクも一緒に変わります。最初に紙の上で決めておけば、その日は1円もかかりません。
RESTの回で決めた型に合わせます。URLはモノ、メソッドが動詞。
| メソッド | URL | ログイン | 何をするか |
|---|---|---|---|
POST | /api/login | 不要 | ログインする |
POST | /api/logout | 要 | ログアウトする |
GET | /api/me | 不要 | いま誰としてログインしているか |
GET | /api/books | 要 | 自分の本の一覧 |
POST | /api/books | 要 | 本を1冊足す |
GET | /api/books/:id | 要 | 本1冊と、その引用 |
PATCH | /api/books/:id | 要 | 本の一部を直す |
DELETE | /api/books/:id | 要 | 本を消す(引用も一緒に消える) |
POST | /api/books/:id/quotes | 要 | その本に引用を足す |
PATCH | /api/quotes/:id | 要 | 引用を直す |
DELETE | /api/quotes/:id | 要 | 引用を消す |
GET | /api/public/quotes | 不要 | 公開されている引用の一覧 |
この表で決まっていることを言葉にします。
- 引用は本に属する。 だから作るときは
/api/books/:id/quotes。本の無い引用は作れません - でも直すときと消すときは
/api/quotes/:id。 すでに存在するものは、それ自体を指せば十分だからです PUTを使っていません。 全部置き換える操作が要らないためです。使わないものは作りません- 公開用は
/api/public/の下にまとめました。 理由は⑧に書きます
URLに
getBooksやdeleteQuoteが1つも無いことを確かめてください。 URLは名詞だけです。
⑤ 一番小さく動くものを、先に通す
この記事の山場です。
上の表には12本あります。12本を全部書いてから node app.js を打ってはいけません。
なぜ駄目なのか。 想像ではなく、実際に起きることを書きます。12本書いて起動すると、こうなります。
Error: connect ECONNREFUSED 127.0.0.1:3306
この1行から分かることは、何もありません。 候補が全部残っているからです。
| 疑わしいところ | 12本書いた後だと |
|---|---|
.env が読まれていない | 分からない |
knexfile.js の client が間違い | 分からない |
hitokoto_app の権限が足りない | 分からない |
| ルートの書き方が間違い | 分からない |
| ミドルウェアの順番が逆 | 分からない |
2本だけ書いて起動していれば、疑うところは2本ぶんしかありません。
「動くところまで書いてから確かめる」は、初心者がいちばん時間を溶かす習慣です。 正しいのは逆です。「確かめられる最小のものを書いて、確かめて、足す」。
いま書くのは、この2本だけです
POST /api/books— 本を1冊入れるGET /api/books— 入れた本を返す
ログインもしません。検証もしません。エラーの形も決めません。 それは後の工程です。
まず、データベースに繋ぐところだけを別ファイルにします。
const knex = require("knex");
const config = require("./knexfile").development;
module.exports = knex(config);
本体です。
const express = require("express");
const db = require("./db");
const app = express();
app.use(express.json());
// いまは仮。⑥で本物のログインに差し替える
const CURRENT_USER_ID = 1;
app.post("/api/books", async (req, res) => {
const [id] = await db("books").insert({
user_id: CURRENT_USER_ID,
title: req.body.title,
author: req.body.author ?? null,
finished_on: req.body.finished_on ?? null,
});
const book = await db("books").where({ id }).first();
res.status(201).json(book);
});
app.get("/api/books", async (req, res) => {
const books = await db("books")
.where({ user_id: CURRENT_USER_ID })
.orderBy("id", "desc");
res.json(books);
});
app.listen(process.env.PORT, () => {
console.log(`listening on ${process.env.PORT}`);
});
利用者がまだ1人もいないので、id = 1 の行だけ手で入れます。
この行は⑥で消します。
password_hashにxと入っている状態を、残したまま先に進まないでください。
動かします。
別のターミナルから叩きます。
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
{"id":1,"user_id":1,"title":"はじめてのUnix","author":"仮の著者","finished_on":"2026-09-10","created_at":"2026-09-14 11:02:31"}
[スクリーンショット: 02_first_two_endpoints.png] POST と GET が続けて通り、登録した本が返ってきているターミナルを撮ってください。
ここまで来たら、この記事の半分は終わっています。
なぜなら、この2本が通った時点で、以下が全部確かめられているからです。
| 確かめられたこと | 通らなければ疑うところだった |
|---|---|
.env が読めている | --env-file の付け忘れ |
| MySQLに繋がっている | ホスト・ポート・権限 |
hitokoto_app が読み書きできる | GRANT の内容 |
| マイグレーションが正しく流れた | 列名・型 |
| Express が本文を受け取れている | express.json() の有無 |
| 外部キーが通っている | user_id の値 |
残りの10本は、ここに足すだけです。 土台はもう検証済みです。
finished_onが"2026-09-10"という文字列で返っているかを確かめてください。2026-09-09T15:00:00.000Zのようになっていたら、knexfile.jsのdateStrings: trueが抜けています。 ここで気づけば1分、画面を作ってから気づくと丸1日です。
⑥ 認証を足す — ただし登録はしない
ここで判断を1つします。
hitokotoに、新規登録の画面は作りません。
使うのは自分1人だからです。登録機能を作ると、こういうものが芋づるで必要になります。
- メールアドレスの重複チェック
- 確認メールの送信(=メールサーバー)
- パスワード再設定
- 迷惑登録の対策
どれも、いまの目的(作品を1つ完成させる)には要りません。 要らないものを作ると、完成しません。
代わりに、管理者を1人 seed で作ります。
シードを書く
seeds/01_admin.js を開きます。
const bcrypt = require("bcryptjs");
exports.seed = async function (knex) {
const email = process.env.ADMIN_EMAIL;
const password = process.env.ADMIN_PASSWORD;
if (!email || !password) {
throw new Error("ADMIN_EMAIL と ADMIN_PASSWORD を .env.migrate に書いてください");
}
const hash = await bcrypt.hash(password, 10);
const existing = await knex("users").where({ email }).first();
if (existing) {
await knex("users").where({ id: existing.id }).update({ password_hash: hash });
console.log(`更新しました: ${email}`);
return;
}
await knex("users").insert({
email,
password_hash: hash,
display_name: "管理者",
});
console.log(`作成しました: ${email}`);
};
ふつうのシードは、最初に
del()で全部消してから入れ直します。 ここではやっていません。usersを消すと、外部キーのRESTRICTに阻まれます(本があるため)。そして阻まれるのが正しい動きです。 だから「あれば更新、無ければ作成」にしました。何度流しても壊れません。
⑤で入れた仮の行を消してから流します。
作成しました: あなたのメールアドレス
入っているものを見ます。
+----+------------------+------------------------+
| id | email | LEFT(password_hash,20) |
+----+------------------+------------------------+
| 1 | you@example.com | $2b$10$Nq8kZ1c0fXe2hR |
+----+------------------+------------------------+
$2b$10$ で始まっていれば bcrypt です。 ハッシュの回で読んだとおり、$10$ がコスト、その後ろにソルトと結果が入っています。
セッションを付ける
app.js の上のほうを書き換えます。
const express = require("express");
const session = require("express-session");
const MySQLStore = require("express-mysql-session")(session);
const bcrypt = require("bcryptjs");
const db = require("./db");
const app = express();
app.use(express.json());
const store = new MySQLStore({
host: process.env.DB_HOST,
user: process.env.DB_USER,
password: process.env.DB_PASSWORD,
database: process.env.DB_NAME,
createDatabaseTable: false, // 表はマイグレーションで作った
schema: {
tableName: "sessions",
columnNames: {
session_id: "session_id",
expires: "expires",
data: "data",
},
},
});
app.use(
session({
secret: process.env.SESSION_SECRET,
store,
resave: false,
saveUninitialized: false,
cookie: {
httpOnly: true,
sameSite: "lax",
secure: false, // ⚠️ https にしたら必ず true にする
maxAge: 1000 * 60 * 60 * 24 * 7,
},
})
);
secure: falseは、いまがhttpだからです。trueにすると Cookie が送られず、ログインできているのにログインできないという一番分かりにくい詰まり方をします。httpsにした日にtrueへ変える。 認証の回と同じ約束です。
ログインと、ログイン確認
app.post("/api/login", async (req, res, next) => {
try {
const { email, password } = req.body ?? {};
const user = await db("users").where({ email: String(email ?? "") }).first();
const hash = user ? user.password_hash : DUMMY_HASH;
const ok = await bcrypt.compare(String(password ?? ""), hash);
if (!user || !ok) {
return res.status(401).json({
error: { code: "INVALID_CREDENTIALS", message: "メールアドレスかパスワードが違います" },
});
}
req.session.userId = user.id;
res.json({ id: user.id, email: user.email, display_name: user.display_name });
} catch (e) {
next(e);
}
});
app.post("/api/logout", requireLogin, (req, res) => {
req.session.destroy(() => res.status(204).end());
});
app.get("/api/me", async (req, res) => {
if (!req.session.userId) return res.json({ user: null });
const user = await db("users")
.select("id", "email", "display_name")
.where({ id: req.session.userId })
.first();
res.json({ user: user ?? null });
});
DUMMY_HASH と requireLogin を上のほうに置きます。
const DUMMY_HASH = bcrypt.hashSync("dummy-not-a-real-password", 10);
function requireLogin(req, res, next) {
if (!req.session.userId) {
return res.status(401).json({
error: { code: "UNAUTHORIZED", message: "ログインしてください" },
});
}
next();
}
DUMMY_HASHは、ハッシュの回で出てきた「時間差を作らない」ためのものです。 存在しないメールアドレスだとbcrypt.compareを通らず一瞬で返るため、応答時間だけで「そのアドレスは登録されている」が分かってしまいます。 無い場合もダミーと照合して、同じだけ待たせます。
CURRENT_USER_ID を消して、req.session.userId に置き換えます。
app.post("/api/books", requireLogin, async (req, res, next) => {
// user_id: req.session.userId
});
app.get("/api/books", requireLogin, async (req, res, next) => {
// .where({ user_id: req.session.userId })
});
確かめます。
HTTP/1.1 401 Unauthorized
{"error":{"code":"UNAUTHORIZED","message":"ログインしてください"}}
ログインしてから、もう一度。 -c で Cookie を保存し、-b で送り返します。
-cを付け忘れると、毎回「ログインしてください」が返ります。 ブラウザは Cookie を自動で保存して自動で送りますが、curlは何もしません。 ここは全員が1回踏みます。
⑦ 入力を検証する — エラーの形を1つに決める
いまの POST /api/books は、これを受け付けます。
タイトルの無い本が入ります。 データベース側は notNullable ですが、undefined が渡ると MySQL は空文字を入れることがあり、しかもエラーは 500 で返ります。利用者には「サーバーが壊れました」としか見えません。
エラーの形を1つに決める
検証の本体は、「弾くこと」ではなく「弾いたことを、いつも同じ形で伝えること」です。
バラバラだと、画面側でこうなります。
文字列が返ることもある / { message: ... } のこともある / 何も返らないこともある
画面側が、そのたびに違う書き方をすることになります。 だから先に1つ決めます。
{ "error": { "code": "VALIDATION_ERROR", "message": "タイトルを入力してください" } }
| キー | 誰が読むか |
|---|---|
code | プログラムが読む。 分岐に使う。変えない |
message | 人が読む。 画面にそのまま出す。変えてよい |
messageで分岐してはいけません。 文言は必ず変わるからです。「タイトルを入力してください」を「本のタイトルは必須です」に直した瞬間に、画面側が壊れます。codeは、そのために存在します。
使う code を決めておきます。
code | HTTPステータス | いつ |
|---|---|---|
VALIDATION_ERROR | 400 | 送られてきた値がおかしい |
INVALID_CREDENTIALS | 401 | ログイン失敗 |
UNAUTHORIZED | 401 | ログインしていない |
FORBIDDEN | 403 | ログインはしているが、他人のもの |
NOT_FOUND | 404 | 無い |
INTERNAL_ERROR | 500 | こちらが壊れた |
検証を書く
class AppError extends Error {
constructor(status, code, message) {
super(message);
this.status = status;
this.code = code;
}
}
const bad = (message) => new AppError(400, "VALIDATION_ERROR", message);
function parseBook(body) {
const b = body ?? {};
const title = typeof b.title === "string" ? b.title.trim() : "";
if (title === "") throw bad("タイトルを入力してください");
if (title.length > 200) throw bad("タイトルは200文字までです");
let author = null;
if (b.author !== undefined && b.author !== null && b.author !== "") {
if (typeof b.author !== "string") throw bad("著者は文字列で送ってください");
author = b.author.trim();
if (author.length > 200) throw bad("著者は200文字までです");
}
let finished_on = null;
if (b.finished_on !== undefined && b.finished_on !== null && b.finished_on !== "") {
if (!/^\d{4}-\d{2}-\d{2}$/.test(String(b.finished_on))) {
throw bad("読了日は 2026-09-14 の形式で送ってください");
}
finished_on = String(b.finished_on);
}
return { title, author, finished_on };
}
function parseQuote(body) {
const b = body ?? {};
const text = typeof b.body === "string" ? b.body.trim() : "";
if (text === "") throw bad("引用の本文を入力してください");
if ([...text].length > 1000) throw bad("引用は1000文字までです");
let page = null;
if (b.page !== undefined && b.page !== null && b.page !== "") {
const n = Number(b.page);
if (!Number.isInteger(n)) throw bad("ページ番号は整数で送ってください");
if (n < 1) throw bad("ページ番号は1以上で送ってください");
if (n > 100000) throw bad("ページ番号が大きすぎます");
page = n;
}
return { body: text, page, is_public: b.is_public === true };
}
module.exports = { AppError, parseBook, parseQuote };
この3つは、必ず落ちてほしいところです。
| 送られるもの | どうなってほしいか |
|---|---|
タイトルが空("" / 空白だけ / 未送信) | 400。 .trim() を通すので、スペースだけも空扱い |
ページ番号が負(-5) | 400。 列は unsigned なので、通すとMySQL側が500で落ちる |
| 引用が長すぎる(1万文字) | 400。 text 型に入ってしまうので、アプリ側で止めるしかない |
[...text].lengthにしているのは、絵文字や一部の漢字が.lengthでは2と数えられるからです。 「1000文字までのはずが、500文字で弾かれた」が起きます。数え方を決めるのも仕様です。
受け止める場所を1つにする
try / catch を12本のルートに書くと、必ずどこかで書き忘れます。 Express のエラーハンドラを、全ルートの後ろに1つ置きます。
const { AppError } = require("./validate");
// ここまでのどのルートにも当たらなかったとき
app.use((req, res) => {
res.status(404).json({
error: { code: "NOT_FOUND", message: "そのURLはありません" },
});
});
// エラーハンドラ。引数が4つであることに意味がある
app.use((err, req, res, next) => {
if (err instanceof AppError) {
return res.status(err.status).json({
error: { code: err.code, message: err.message },
});
}
console.error(err);
res.status(500).json({
error: { code: "INTERNAL_ERROR", message: "サーバー側で問題が起きました" },
});
});
引数が
(err, req, res, next)の4つのときだけ、Express はそれをエラーハンドラとして扱います。 3つに減らすと、ただのミドルウェアになり、エラーは Express 組み込みのハンドラが受けて HTML の 500 を返します。決めたエラーの形では返らなくなります。 ここは見た目で気づけません。
console.error(err)で中身をログに出し、利用者には出していません。 エラーの本文には、テーブル名やSQLがそのまま入っています。 セキュリティの回でやった「余計なことを喋らない」の具体形です。
各ルートは、こうなります。
app.post("/api/books", requireLogin, async (req, res, next) => {
try {
const input = parseBook(req.body);
const [id] = await db("books").insert({ ...input, user_id: req.session.userId });
const book = await db("books").where({ id }).first();
res.status(201).json(book);
} catch (e) {
next(e);
}
});
next(e) に渡すだけです。 形を決めるのは、いちばん下の1箇所だけになりました。
他人のものを触らせない
ログインしているかどうかと、それが自分のものかどうかは別の話です。 認証と認可の区別です。
async function myBookOr404(bookId, userId) {
const book = await db("books")
.where({ id: Number(bookId), user_id: userId })
.first();
if (!book) throw new AppError(404, "NOT_FOUND", "その本はありません");
return book;
}
他人の本を触ろうとしたとき、
403ではなく404を返しています。403(あなたには権限がない)だと、「そのIDの本は存在する」という情報を渡してしまいます。1から順に叩けば、何冊あるか数えられます。 無いことにするのが安全です。
引用のほうは、quotes から books を辿って持ち主を確かめます。
async function myQuoteOr404(quoteId, userId) {
const row = await db("quotes")
.join("books", "books.id", "quotes.book_id")
.where("quotes.id", Number(quoteId))
.andWhere("books.user_id", userId)
.select("quotes.*")
.first();
if (!row) throw new AppError(404, "NOT_FOUND", "その引用はありません");
return row;
}
quotes に user_id を持たせていないのは、正規化の結果です。 持ち主は books が知っているので、2箇所に書きません。 そのぶん join が1つ増えます。これが正規化の代金です。
⑧ 公開用のAPIを、別の道にする
公開ページは、ログインしていない人が読みます。
ここでやりがちな書き方が、これです。
// ❌ こうしない
app.get("/api/quotes", async (req, res) => {
if (req.session.userId) {
// 全部返す
} else {
// 公開のものだけ返す
}
});
動きます。そして、いつか漏れます。
| なぜ漏れるか |
|---|
if の中を後から直したとき、片方だけ直す |
| 列を1つ足したとき、公開側で隠し忘れる |
| 「ログイン中だから全部返す」の判定が、1箇所でも抜けたら全公開 |
分けます。
app.get("/api/public/quotes", async (req, res, next) => {
try {
const rows = await db("quotes")
.join("books", "books.id", "quotes.book_id")
.join("users", "users.id", "books.user_id")
.where("quotes.is_public", true)
.orderBy("quotes.created_at", "desc")
.limit(50)
.select(
"quotes.id",
"quotes.body",
"quotes.page",
"quotes.created_at",
"books.title as book_title",
"books.author as book_author",
"users.display_name as author_name"
);
res.json(rows);
} catch (e) {
next(e);
}
});
このルートで守られていること。
requireLoginを付けていない。 誰でも読めるwhere("quotes.is_public", true)が消せない。ifの外にあるので、分岐で外れることがありませんselectで列を名指ししている。quotes.*にしていないので、あとでmemoのような列を足しても、勝手には出ませんusersから出すのはdisplay_nameだけ。 メールアドレスは選んでいませんlimit(50)。 全部返さない
「ログイン不要のものは別の道にする」を、URLの形にも出しています。
/api/public/で始まるものは、外から読まれる。 これだけ覚えておけば、後から見た人も間違えません。ifは読まないと分かりませんが、URLは見れば分かります。
確かめます。Cookie を送らずに叩きます。
[]
空の配列が返れば正しい動きです。 まだ is_public が true の引用が1つも無いためです。401 が返ってきたら、requireLogin が付いています。
⑨ curl で全部叩く
画面は1枚もありません。それでもAPIは完成します。
ここを飛ばして画面に進むと、こうなります。「ボタンを押しても何も起きない」→ 画面が悪いのかAPIが悪いのか分からない → 2つ同時に直そうとして、両方壊れる。
先にAPIだけを確定させます。
| # | 打つもの | 期待する結果 |
|---|---|---|
| 1 | curl -i -s $BASE/api/books | 401 UNAUTHORIZED |
| 2 | ログイン(パスワードをわざと間違える) | 401 INVALID_CREDENTIALS |
| 3 | ログイン(正しい) | 200 と自分の情報 |
| 4 | curl -s -b $C $BASE/api/me | 200 user が null でない |
| 5 | 本を登録 | 201 と id |
| 6 | タイトル空で登録 | 400 VALIDATION_ERROR |
| 7 | 一覧 | 200 と1件 |
| 8 | 引用を足す | 201 |
| 9 | ページ番号 -5 で足す | 400 |
| 10 | 引用を公開に変える | 200 is_public が true |
| 11 | Cookie無しで /api/public/quotes | 200 と1件 |
| 12 | 存在しない本を消す | 404 NOT_FOUND |
| 13 | 本を消す | 204。引用も消えている |
| 14 | ログアウト | 204 |
上から順に打ちます。
13の後で、これを打ちます。
+--------+
| quotes |
+--------+
| 0 |
+--------+
本を消したら、引用も消えています。 DELETE FROM quotes を1行も書いていません。マイグレーションに書いた ON DELETE CASCADE が、データベースの側で消しています。
これがマイグレーションから書いた見返りです。 消し忘れが、アプリのバグとして起きようがありません。
[スクリーンショット: 03_curl_all.png] 上の表の 1〜14 を通し終えたターミナルを撮ってください。401 と 400 と 404 が並んでいるところが写っていれば十分です。
14個が全部期待どおりなら、サーバー側は完成です。 画面がまだ無くても、です。
⑩ systemd で常駐させる
「開発中だから、ターミナルで node app.js のままでいい」と考えたくなります。やめます。
| そのままだと | 常駐させると |
|---|---|
| SSHを切ると止まる | 切っても動く |
| 落ちたことに気づかない | systemctl status で分かる |
| なぜ落ちたか残らない | journalctl に残る |
| VMを再起動すると止まる | enable していれば戻る |
開発中こそ、落ちたら気づける形にします。 気づかないまま「なんか繋がらない」と1時間溶かすのが、いちばん高くつきます。
Node の場所を調べます。 nvm で入れていると、パスが人によって違います。
/home/ユーザー名/.nvm/versions/node/v22.14.0/bin/node
[Unit]
Description=hitokoto app
After=network.target mysql.service
[Service]
Type=simple
User=ユーザー名
WorkingDirectory=/home/ユーザー名/hitokoto
EnvironmentFile=/home/ユーザー名/hitokoto/.env
ExecStart=/home/ユーザー名/.nvm/versions/node/v22.14.0/bin/node /home/ユーザー名/hitokoto/app.js
Restart=on-failure
RestartSec=3
[Install]
WantedBy=multi-user.target
2つ、前と変えているところがあります。
| 行 | 意味 |
|---|---|
EnvironmentFile= | --env-file の代わり。 systemd が .env を読んで環境変数として渡す |
Restart=on-failure | 異常終了したら3秒後に起動し直す。 正常終了(systemctl stop)では戻らない |
EnvironmentFileは、.envの書き方に少しうるさいです。 値を"で囲まないでください。 囲むと、引用符ごと値として渡ります。#から始まる行はコメントとして無視されます。
[スクリーンショット: 04_systemctl_status.png] systemctl status hitokoto が active (running) になっている画面を撮ってください。
enable と start は別物でした(プロセスとサービスの回)。--now は両方まとめてやる指定です。
わざと落として、戻ることを確かめます。
stop で止めた後は戻りません。 pkill で殺したときだけ戻ります。それが on-failure の意味です。
Restart=alwaysにしないでください。 正常に終了した(終了コード0の)ときまで起動し直します。 ただしon-failureでも、.envの書き間違いで起動に失敗している場合は、3秒ごとに起動し続けます。 ログが埋まり、CPUを食い、そのうち何が原因だったのか読めなくなります。 起動回数の上限(既定は10秒に5回)はRestart=の種類に関係なく掛かりますが、RestartSec=3だと10秒に4回までしか起動しないので届きません。諦めさせたいなら、[Unit]にStartLimitIntervalSec=60とStartLimitBurst=5のように明示してください(60秒に5回起動したら止まります)。
外からも繋げるようにするなら、ポートを開けます。
これは開発中のVMだからやっています。 本番では、3001 を直接開けず、nginx のリバースプロキシの後ろに置きます。 そこは公開の回でやります。
やらないと決めたこと
動くようになると、足したくなります。 ここで一度、足さないものを書き出します。
| 足したくなるもの | いま足さない理由 |
|---|---|
| ユーザー登録 | 使うのは1人。メール送信という別の山が付いてくる |
| テストコード | 次の回でやる。 いま書くと、仕様がまだ動くので書き直しになる |
routes/ にファイルを分ける | app.js がまだ読める長さ。 分けるのは、読めなくなってから |
| TypeScript を入れる | いま入れると、型を直す時間で完成が遠のく |
| ページング | 本が数千冊になってからでいい。limit(50) で足りている |
PUT | 使う場面が無い。 使わないものは作らない |
| 画像アップロード / 通知 / フォロー / 全文検索 | 最初に「やらないこと」に入れた。 揺らさない |
「作品が完成しない」のいちばんの原因は、難しさではありません。 終わりを決めていないことです。 上の表は、決めた終わりを守るための表です。
つまずいたところ
実際に詰まった順に書きます。
Access denied for user ''@'localhost'
npx knex migrate:latest と打ちました。 前回と同じ間違いです。
npx を通すと --env-file が届きません。 環境変数が空のまま Knex が起動するので、利用者名が空文字になります。
この長い形で打ちます。 毎回打つのが嫌になったので、package.json の scripts に入れました。
"scripts": {
"migrate": "node --env-file=.env.migrate node_modules/knex/bin/cli.js migrate:latest",
"migrate:status": "node --env-file=.env.migrate node_modules/knex/bin/cli.js migrate:status",
"seed": "node --env-file=.env.migrate node_modules/knex/bin/cli.js seed:run",
"start": "node --env-file=.env app.js"
}
CREATE command denied to user 'hitokoto_app'
アプリを起動した瞬間に出ました。 express-mysql-session が sessions 表を自分で作ろうとしたためです。
これは正しい失敗です。 hitokoto_app に CREATE を与えていません。
createDatabaseTable: false を書き、表はマイグレーションで作ります。 ここで「じゃあ権限を足そう」と考えたら、②で権限を分けた意味が消えます。
読了日が1日ずれる
2026-09-10 で登録したのに、GET すると 2026-09-09T15:00:00.000Z が返りました。
mysql2 が DATE 型を JavaScript の Date にして、UTCに直すためです。 日本時間の 9/10 00:00 は、UTCでは 9/9 15:00 です。
knexfile.js の connection に dateStrings: true を入れて解決しました。日付だけの列は、文字列のまま扱います。
画面を作ってから気づくと、直す場所が3箇所になります(サーバー・画面・すでに入ったデータ)。API だけの段階で気づけたのが救いでした。
curl が毎回「ログインしてください」
ログインは 200 で返ってくるのに、次の curl が 401 でした。
-c と -b を付けていませんでした。 ブラウザなら勝手にやってくれることを、curl は一切やりません。
中身も見られます。
connect.sid という名前で、署名付きの文字列が1行入っています。 認証の回で読んだ「サーバーが覚えて、利用者には札だけ渡す」が、ここに実物としてあります。
エラーが 500 のままだった
AppError を投げているのに、いつも INTERNAL_ERROR が返りました。
エラーハンドラを app.use(express.json()) のすぐ下に置いていました。 Express のミドルウェアは書いた順に上から通ります。ルートより前に置いたエラーハンドラは、ルートで起きたエラーを受け取れません。
エラーハンドラは、いちばん下です。 404 のハンドラも、全ルートの後ろです。
PATCH が 404 になる
/api/quotes/1 を叩いたのに、NOT_FOUND でした。
引用は消えていませんでした。 myQuoteOr404 の join の条件を books.id = quotes.id と書いていました(book_id の書き忘れ)。
join は、間違っていても静かに動きます。 0行返るだけです。エラーになりません。 疑ったのは where のほうで、join に気づくのに30分かかりました。
Knex が実際に投げているSQLを見て、やっと分かりました。
console.log(
db("quotes").join("books", "books.id", "quotes.book_id")
.where("quotes.id", 1).toString()
);
.toString() で、送る前のSQLが読めます。 「動かない」ときに最初に打つべきものでした。
まとめ
- 作品は、練習用のフォルダの続きに作らない。 空から始めないと、何が必要かが永久に分からない
.envと.gitignoreは、コードを1行も書く前に作る。 後回しにしたものは、やらない- データベースの利用者は、アプリ用と移行用で分ける。 アプリが動いている間、表を消せる必要は無い
- テーブルは
CREATE TABLEで作らない。 マイグレーションを書いたら表ができる、という向きにする ON DELETEは「親が消えたとき、この子は単独で意味を持つか」で決める。 持つならRESTRICT、持たないならCASCADE。同じアプリの中で混ざるのが普通- URLは、コードを書く前に表で全部決める。 後から変えるのがいちばん高い
- 全部書いてから動かさない。 最初に通すのは
POSTとGETの2本だけ。この2本が通れば、土台は全部検証済みになる - 登録画面は、作品に必ず要るものではない。 一人で使うなら
seedで足りる。要らないものを作ると完成しない - 検証の本体は「弾くこと」ではなく「同じ形で伝えること」。
{ error: { code, message } }に揃える messageで分岐しない。 文言は変わる。そのためにcodeがある- 他人のものは
403ではなく404。403は「存在する」を教えてしまう - ログイン不要のAPIは
ifで分けず、URLごと別にする。ifは読まないと分からないが、URLは見れば分かる - エラーハンドラは、いちばん下。引数は4つ。 3つだとただのミドルウェアになる
- 画面が1枚も無くても、APIは完成させられる。
curlが14個通ったら、そこは終わっている - 開発中こそ常駐させる。 落ちたことに気づけない時間が、いちばん高くつく
Restart=alwaysにしない。 ただしon-failureでも失敗し続けるので、諦めさせるならStartLimitIntervalSec/StartLimitBurstを明示する
参考リンク
- roadmap.sh — Backend Developer
- Express — ルーティング
- Express — エラーハンドリング
- Knex.js — Schema Builder
- Knex.js — Migrations と Seeds
- express-session
- express-mysql-session
- bcryptjs
- MySQL — 外部キー制約
- MDN — HTTPレスポンスステータスコード
- curl — マニュアル
- systemd.service — 設定項目
次に読む
この記事は 【第9段階】作品を1つ完成させる の 2 / 10 本目です。
| 記事 | |
|---|---|
| ← 前の記事 | 作らないものリストを先に書く — 個人開発の題材選び |
| → 次の記事 | 「動く」と「使える」の差は4つの状態 — Reactの画面 |
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
作品づくり。使う技術は第0〜第8段階で扱ったものだけで、新しい項目は出てこない。

コメント