全部書いてから動かさない — 作品のAPIと認証

作品のAPIと認証。APIの書類とデータベース、ログインの鍵とチェック。

ここから実際に手を動かします。そして最初にやることは、コードを書くことではありません。

前回: 作らないものリストを先に書く — 個人開発の題材選び 作業場所はVMの中(Ubuntu Server)です。Node.js と MySQL が入っていて、~/server で Express と ORMとマイグレーションの基本|スキーマ変更を手で打たない仕組み が動いた経験がある状態から始めます。~/server は今回いっさい開きません。

前回までで、作るものが決まりました。hitokoto(ひとこと) — 読んだ本と、そこから引いた一文を残すアプリです。

bash
$ mkdir ~/hitokoto

新しいフォルダを作ります。 ~/server の続きにはしません。

理由を先に書きます。 ~/server は、サーバーとは何かからREST、認証まで、試したことが全部積み上がった場所です。動かなくなった実験も、途中でやめたコードも、消し忘れたテーブルも入っています。

あれは教材です。作品ではありません。

混ぜると、こうなります。

混ぜると起きることなぜ困るか
どこまでが作品か分からなくなる人に見せるとき、「この部分は関係ありません」と言い訳することになる
消していいものが判断できない練習で作った tasks テーブルを消したら、作品が動かなくなる、が起こる
git init する範囲が決まらない履歴の1行目から、練習の残骸が混ざる
再現できない「動いています」と言えても、別のVMに持っていくと動かない。何が要るのか分からないため

作品は、まっさらな場所から作ります。 これは几帳面さの話ではなく、「動かせる」ではなく「仕組みが分かる」を守るための話です。何が要って何が要らないかは、空の状態から1つずつ入れたときにしか分かりません。

対象レベル: 中級 / 区分: 必修

目次

この記事でわかること

  • 練習用のフォルダの続きに作品を作ってはいけないこと。何が必要かは、空から始めたときにしか分からないこと
  • テーブルは CREATE TABLE で作らないこと。先にマイグレーションという「変更の履歴」を作り、そこからテーブルが生まれるという順番
  • 外部キーの ON DELETE は「どれが正しい」ではなく「消えていいものかどうか」で選ぶこと。同じアプリの中で違う指定が混ざるのが普通だということ
  • 全部書いてから動かすと、どこが壊れているのか永久に分からなくなること。最初に通すのは2本だけでいいこと
  • 登録画面は、作品に必ず要るものではないこと。一人で使うなら、利用者は seed で作れば足りること
  • 入力の検証は「あるかないか」ではなく「エラーの形が1つに揃っているか」が本体だということ
  • ログイン不要のAPIは、if で分岐させず、URLごと別の道にしたほうが事故らないこと
  • 画面が1枚も無くても、APIは完成させられること。curl が通れば、そこは終わっている

この記事でやること

  1. ~/hitokoto を新しく作り、.env とデータベースの利用者をコードより先に用意する
  2. マイグレーションを3枚書いて users / books / quotes を作る。外部キーと ON DELETE を用途で選び分ける
  3. APIのURLを、表にして先に全部決める
  4. POST /api/books と GET /api/books の2本だけを書いて通す。動いてから次を足す
  5. 管理者1人を seed で作り、書き込みだけログインを要求する
  6. 入力の検証とエラーの形を揃え、公開用のAPIを別の道に分ける
  7. curl で全部叩いて確かめ、systemd で常駐させる

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
マイグレーションデータベースの変更を1件ずつ記録したファイル。 実行すると表ができ、巻き戻すと消える
シード(seed)最初から入っていてほしいデータを入れる仕組み。 この記事では管理者を1人だけ作る
エンドポイントAPIの入口1つ。GET /api/books のようなメソッドとURLの組み合わせ
バリデーション送られてきた値が使える形か確かめること。 日本語では「検証」
ON DELETE参照先が消えたとき、参照している側をどうするかの指定
CASCADE一緒に消す。 親が消えたら子も消える
RESTRICT消させない。 子がいる間は親を削除できない
ミドルウェアExpress で、本処理の前に必ず通る関数。 ログイン確認などをここに置く
seed:runシードを実際に流すコマンド

この記事のコードは、いままで書いたものより長くなります。 一気に読まないでください。 ⑤の「2本だけ通す」まで来たら、そこで一度手を止めて curl を打つのが、この記事のいちばん大事な使い方です。

① 場所を作る

bash
$ mkdir ~/hitokoto
$ cd ~/hitokoto
$ npm init -y

入れるものを、理由と一緒に並べます。

パッケージ何のため
expressHTTPを受ける。APIの回で生のNodeから乗り換えたもの
knexマイグレーションとSQLの組み立て
mysql2Knex が MySQL と話すためのドライバ
express-sessionログイン状態を覚える
express-mysql-sessionその記憶をメモリではなくMySQLに置く
bcryptjsパスワードを戻せない形にする
bash
$ npm install express knex mysql2 express-session express-mysql-session bcryptjs

bcrypt ではなく bcryptjs です。 理由はパスワード保存の回に書いたとおりで、bcrypt はビルド済みの部品が使えない環境(ビルド済みが用意されていない Node の版など)では入れるときにコンパイルが走り、素のUbuntu Serverにはそのための道具が入っていません。

.gitignore を、コードを1行も書く前に作ります。

bash
$ cat > ~/hitokoto/.gitignore <<'EOF'
  node_modules/
  .env
  .env.migrate
  EOF

これを後回しにすると、.env が履歴に入ったまま気づかない、が起きます。 一度コミットされた秘密は、そのファイルを消しても履歴には残ります。 Gitの導入の回で触れた話が、ここで効いてきます。

② .env を最初に作る

コードより先に、置き場所と鍵を決めます。 「あとで環境変数に出す」は、ほぼ確実にやりません。

まずデータベースと、利用者を2人作ります。

bash
$ sudo mysql
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 は表を作れません。 だから、アプリのバグや外からの攻撃で表が消えることが構造的に起きません。表を作り替えるのは、人が意識して打つマイグレーションのときだけです。

パスワードを作ります。

bash
$ openssl rand -base64 24
$ openssl rand -base64 24
$ openssl rand -base64 32

3つ出た文字列を、こう振り分けます。

bash
$ nano ~/hitokoto/.env
DB_HOST=127.0.0.1
DB_USER=hitokoto_app
DB_PASSWORD=(1つ目)
DB_NAME=hitokoto
SESSION_SECRET=(3つ目)
PORT=3001
bash
$ nano ~/hitokoto/.env.migrate
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 を書きます。

bash
$ nano ~/hitokoto/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枚に分ける

bash
$ cd ~/hitokoto
$ node --env-file=.env.migrate node_modules/knex/bin/cli.js migrate:make 001_users
$ node --env-file=.env.migrate node_modules/knex/bin/cli.js migrate:make 002_books_and_quotes
$ node --env-file=.env.migrate node_modules/knex/bin/cli.js migrate:make 003_sessions

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.idRESTRICT本が1冊でもある人は消せない利用者を消したら本が全部消える、は取り返しがつかない。先に本を消せ、と機械に言わせる
quotes.book_id → books.idCASCADE本を消すと、その本の引用も消える本の無い引用に意味が無い。残しても誰も読めない孤児になる

「どちらが正しいか」ではありません。 同じアプリの中で違う指定が混ざるのが普通です。 判断は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 が決めています。 ここだけは自由に付けられません。ライブラリが読みに来る名前だからです。

流す

bash
$ cd ~/hitokoto
$ node --env-file=.env.migrate node_modules/knex/bin/cli.js migrate:latest
$ node --env-file=.env.migrate node_modules/knex/bin/cli.js migrate:status

[スクリーンショット: 01_migrate_status.png] migrate:status を実行して、3枚とも Completed と出ている画面を撮ってください。

確かめます。

bash
$ mysql -u hitokoto_migrator -p hitokoto -e "SHOW TABLES;"
+--------------------+
| Tables_in_hitokoto |
+--------------------+
| books              |
| knex_migrations    |
| knex_migrations_lock |
| quotes             |
| sessions           |
| users              |
+--------------------+

knex_migrations は、Knex が「どこまで流したか」を覚えている表です。 ここを手で書き換えると迷子になります。触りません。

外部キーが本当に効いているか、1回だけ試します。

bash
$ mysql -u hitokoto_migrator -p hitokoto -e "INSERT INTO books (user_id, title) VALUES (999, 'test');"
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 — 入れた本を返す

ログインもしません。検証もしません。エラーの形も決めません。 それは後の工程です。

まず、データベースに繋ぐところだけを別ファイルにします。

bash
$ nano ~/hitokoto/db.js
const knex = require("knex");
const config = require("./knexfile").development;

module.exports = knex(config);

本体です。

bash
$ nano ~/hitokoto/app.js
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 の行だけ手で入れます。

bash
$ mysql -u hitokoto_migrator -p hitokoto -e "INSERT INTO users (email, password_hash, display_name) VALUES ('tmp@example.com', 'x', '仮');"

この行は⑥で消します。 password_hash に x と入っている状態を、残したまま先に進まないでください。

動かします。

bash
$ cd ~/hitokoto
$ node --env-file=.env app.js

別のターミナルから叩きます。

bash
$ curl -i -s -X POST http://localhost:3001/api/books \
    -H "Content-Type: application/json" \
    -d '{"title":"はじめてのUnix","author":"仮の著者","finished_on":"2026-09-10"}'
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"}
bash
$ curl -s http://localhost:3001/api/books

[スクリーンショット: 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 で作ります。

シードを書く

bash
$ cd ~/hitokoto
$ node --env-file=.env.migrate node_modules/knex/bin/cli.js seed:make 01_admin

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 に阻まれます(本があるため)。そして阻まれるのが正しい動きです。 だから「あれば更新、無ければ作成」にしました。何度流しても壊れません。

⑤で入れた仮の行を消してから流します。

bash
$ mysql -u hitokoto_migrator -p hitokoto -e "DELETE FROM books; DELETE FROM users;"
$ cd ~/hitokoto
$ node --env-file=.env.migrate node_modules/knex/bin/cli.js seed:run
作成しました: あなたのメールアドレス

入っているものを見ます。

bash
$ mysql -u hitokoto_migrator -p hitokoto -e "SELECT id, email, LEFT(password_hash, 20) FROM users;"
+----+------------------+------------------------+
| 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 })
});

確かめます。

bash
$ curl -i -s http://localhost:3001/api/books
HTTP/1.1 401 Unauthorized

{"error":{"code":"UNAUTHORIZED","message":"ログインしてください"}}

ログインしてから、もう一度。 -c で Cookie を保存し、-b で送り返します。

bash
$ curl -s -c /tmp/cookie.txt -X POST http://localhost:3001/api/login \
    -H "Content-Type: application/json" \
    -d '{"email":"you@example.com","password":"あなたのパスワード"}'

$ curl -s -b /tmp/cookie.txt http://localhost:3001/api/books

-c を付け忘れると、毎回「ログインしてください」が返ります。 ブラウザは Cookie を自動で保存して自動で送りますが、curl は何もしません。 ここは全員が1回踏みます。

⑦ 入力を検証する — エラーの形を1つに決める

いまの POST /api/books は、これを受け付けます。

bash
$ curl -s -b /tmp/cookie.txt -X POST http://localhost:3001/api/books \
    -H "Content-Type: application/json" -d '{}'

タイトルの無い本が入ります。 データベース側は notNullable ですが、undefined が渡ると MySQL は空文字を入れることがあり、しかもエラーは 500 で返ります。利用者には「サーバーが壊れました」としか見えません。

エラーの形を1つに決める

検証の本体は、「弾くこと」ではなく「弾いたことを、いつも同じ形で伝えること」です。

バラバラだと、画面側でこうなります。

文字列が返ることもある / { message: ... } のこともある / 何も返らないこともある

画面側が、そのたびに違う書き方をすることになります。 だから先に1つ決めます。

{ "error": { "code": "VALIDATION_ERROR", "message": "タイトルを入力してください" } }
キー誰が読むか
codeプログラムが読む。 分岐に使う。変えない
message人が読む。 画面にそのまま出す。変えてよい

message で分岐してはいけません。 文言は必ず変わるからです。「タイトルを入力してください」を「本のタイトルは必須です」に直した瞬間に、画面側が壊れます。 code は、そのために存在します。

使う code を決めておきます。

codeHTTPステータスいつ
VALIDATION_ERROR400送られてきた値がおかしい
INVALID_CREDENTIALS401ログイン失敗
UNAUTHORIZED401ログインしていない
FORBIDDEN403ログインはしているが、他人のもの
NOT_FOUND404無い
INTERNAL_ERROR500こちらが壊れた

検証を書く

bash
$ nano ~/hitokoto/validate.js
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 を送らずに叩きます。

bash
$ curl -s http://localhost:3001/api/public/quotes
[]

空の配列が返れば正しい動きです。 まだ is_public が true の引用が1つも無いためです。401 が返ってきたら、requireLogin が付いています。

⑨ curl で全部叩く

画面は1枚もありません。それでもAPIは完成します。

ここを飛ばして画面に進むと、こうなります。「ボタンを押しても何も起きない」→ 画面が悪いのかAPIが悪いのか分からない → 2つ同時に直そうとして、両方壊れる。

先にAPIだけを確定させます。

bash
$ BASE=http://localhost:3001
$ C=/tmp/cookie.txt
#打つもの期待する結果
1curl -i -s $BASE/api/books401 UNAUTHORIZED
2ログイン(パスワードをわざと間違える)401 INVALID_CREDENTIALS
3ログイン(正しい)200 と自分の情報
4curl -s -b $C $BASE/api/me200 user が null でない
5本を登録201 と id
6タイトル空で登録400 VALIDATION_ERROR
7一覧200 と1件
8引用を足す201
9ページ番号 -5 で足す400
10引用を公開に変える200 is_public が true
11Cookie無しで /api/public/quotes200 と1件
12存在しない本を消す404 NOT_FOUND
13本を消す204。引用も消えている
14ログアウト204

上から順に打ちます。

bash
$ curl -i -s $BASE/api/books

$ curl -i -s -X POST $BASE/api/login \
    -H "Content-Type: application/json" \
    -d '{"email":"you@example.com","password":"まちがい"}'

$ curl -s -c $C -X POST $BASE/api/login \
    -H "Content-Type: application/json" \
    -d '{"email":"you@example.com","password":"正しいパスワード"}'

$ curl -s -b $C $BASE/api/me

$ curl -s -b $C -X POST $BASE/api/books \
    -H "Content-Type: application/json" \
    -d '{"title":"考えるヒント","author":"仮の著者","finished_on":"2026-09-12"}'

$ curl -i -s -b $C -X POST $BASE/api/books \
    -H "Content-Type: application/json" -d '{"title":"   "}'

$ curl -s -b $C $BASE/api/books

$ curl -s -b $C -X POST $BASE/api/books/1/quotes \
    -H "Content-Type: application/json" \
    -d '{"body":"読むとは、書いた人の速度に合わせることだ","page":42}'

$ curl -i -s -b $C -X POST $BASE/api/books/1/quotes \
    -H "Content-Type: application/json" \
    -d '{"body":"テスト","page":-5}'

$ curl -s -b $C -X PATCH $BASE/api/quotes/1 \
    -H "Content-Type: application/json" -d '{"is_public":true}'

$ curl -s $BASE/api/public/quotes

$ curl -i -s -b $C -X DELETE $BASE/api/books/9999

$ curl -i -s -b $C -X DELETE $BASE/api/books/1

$ curl -i -s -b $C -X POST $BASE/api/logout

13の後で、これを打ちます。

bash
$ mysql -u hitokoto_migrator -p hitokoto -e "SELECT COUNT(*) AS quotes FROM quotes;"
+--------+
| 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 で入れていると、パスが人によって違います。

bash
$ which node
/home/ユーザー名/.nvm/versions/node/v22.14.0/bin/node
bash
$ sudo nano /etc/systemd/system/hitokoto.service
[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 の書き方に少しうるさいです。 値を " で囲まないでください。 囲むと、引用符ごと値として渡ります。# から始まる行はコメントとして無視されます。

bash
$ sudo systemctl daemon-reload
$ sudo systemctl enable --now hitokoto
$ systemctl status hitokoto

[スクリーンショット: 04_systemctl_status.png] systemctl status hitokoto が active (running) になっている画面を撮ってください。

enable と start は別物でした(プロセスとサービスの回)。--now は両方まとめてやる指定です。

わざと落として、戻ることを確かめます。

bash
$ sudo systemctl stop hitokoto
$ pkill -f "hitokoto/app.js"

stop で止めた後は戻りません。 pkill で殺したときだけ戻ります。それが on-failure の意味です。

bash
$ sudo systemctl start hitokoto
$ pkill -f "hitokoto/app.js"
$ systemctl status hitokoto
$ journalctl -u hitokoto -n 30 --no-pager

Restart=always にしないでください。 正常に終了した(終了コード0の)ときまで起動し直します。 ただし on-failure でも、.env の書き間違いで起動に失敗している場合は、3秒ごとに起動し続けます。 ログが埋まり、CPUを食い、そのうち何が原因だったのか読めなくなります。 起動回数の上限(既定は10秒に5回)は Restart= の種類に関係なく掛かりますが、RestartSec=3 だと10秒に4回までしか起動しないので届きません。諦めさせたいなら、[Unit] に StartLimitIntervalSec=60 と StartLimitBurst=5 のように明示してください(60秒に5回起動したら止まります)。

外からも繋げるようにするなら、ポートを開けます。

bash
$ sudo ufw allow 3001/tcp
$ sudo ufw status

これは開発中のVMだからやっています。 本番では、3001 を直接開けず、nginx のリバースプロキシの後ろに置きます。 そこは公開の回でやります。

やらないと決めたこと

動くようになると、足したくなります。 ここで一度、足さないものを書き出します。

足したくなるものいま足さない理由
ユーザー登録使うのは1人。メール送信という別の山が付いてくる
テストコード次の回でやる。 いま書くと、仕様がまだ動くので書き直しになる
routes/ にファイルを分けるapp.js がまだ読める長さ。 分けるのは、読めなくなってから
TypeScript を入れるいま入れると、型を直す時間で完成が遠のく
ページング本が数千冊になってからでいい。limit(50) で足りている
PUT使う場面が無い。 使わないものは作らない
画像アップロード / 通知 / フォロー / 全文検索最初に「やらないこと」に入れた。 揺らさない

「作品が完成しない」のいちばんの原因は、難しさではありません。 終わりを決めていないことです。 上の表は、決めた終わりを守るための表です。

つまずいたところ

実際に詰まった順に書きます。

Access denied for user ''@'localhost'

npx knex migrate:latest と打ちました。 前回と同じ間違いです。

npx を通すと --env-file が届きません。 環境変数が空のまま Knex が起動するので、利用者名が空文字になります。

bash
$ node --env-file=.env.migrate node_modules/knex/bin/cli.js migrate:latest

この長い形で打ちます。 毎回打つのが嫌になったので、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 は一切やりません。

bash
$ curl -c /tmp/cookie.txt ...   # 受け取ったCookieを保存
$ curl -b /tmp/cookie.txt ...   # 保存したCookieを送る

中身も見られます。

bash
$ cat /tmp/cookie.txt

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 を明示する

参考リンク


次に読む

この記事は 【第9段階】作品を1つ完成させる の 2 / 10 本目です。

記事
← 前の記事作らないものリストを先に書く — 個人開発の題材選び
→ 次の記事「動く」と「使える」の差は4つの状態 — Reactの画面

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

作品づくり。使う技術は第0〜第8段階で扱ったものだけで、新しい項目は出てこない。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次