Схемы ответа и сериализация

Сериализация — превращение объекта JavaScript в строку JSON перед отправкой клиенту. Если описать схему ответа, Fastify соберёт JSON по ней: это быстрее обычного JSON.stringify и заодно защищает от утечки полей, которых нет в схеме.

Схема ответа

Схемы ответа задают в schema.response отдельно для каждого кода. Пусть у статей в src/routes/posts.js появилось служебное поле authorEmail, которое клиентам видеть не нужно:

// src/routes/posts.js
const posts = [
  { id: 1, title: 'Первая статья', body: 'Текст', authorEmail: 'anna@example.com' },
];
 
const showSchema = {
  params: {
    type: 'object',
    properties: { id: { type: 'integer' } },
  },
  response: {
    200: {
      type: 'object',
      properties: {
        id: { type: 'integer' },
        title: { type: 'string' },
        body: { type: 'string' },
      },
    },
  },
};
 
app.get('/posts/:id', { schema: showSchema }, async (request) => {
  return posts.find((post) => post.id === request.params.id);
});

Откройте http://localhost:3000/posts/1 — в ответе будут только id, title и body. Поле authorEmail отброшено, потому что его нет в схеме.

Список

Для массива указывают type: 'array' и схему элемента в items:

// src/routes/posts.js
const listSchema = {
  response: {
    200: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          id: { type: 'integer' },
          title: { type: 'string' },
        },
      },
    },
  },
};
 
app.get('/posts', { schema: listSchema }, async () => posts);

Список /posts теперь отдаёт только id и title — тексты статей нужны лишь на странице одной статьи.

Общие схемы

Чтобы не повторять описание статьи в каждом маршруте, его регистрируют один раз через addSchema с идентификатором $id. Добавьте в src/app.js до подключения маршрутов:

// src/app.js
app.addSchema({
  $id: 'post',
  type: 'object',
  properties: {
    id: { type: 'integer' },
    title: { type: 'string' },
    body: { type: 'string' },
  },
});

Теперь в маршрутах можно сослаться на неё через $ref:

// src/routes/posts.js
const showSchema = {
  response: {
    200: { $ref: 'post#' },
  },
};

Ответ будет тем же, а описание статьи хранится в одном месте.

Несколько кодов

Частая ошибка

Новое поле, которое вы добавили в данные, но забыли в схеме ответа, молча исчезает из JSON. Если, например, createdAt пропал из ответа без всяких ошибок — первым делом проверьте schema.response.