Інтеграція клінічних та державних API у Headless-архітектурі: досвід USDA FoodData Central у Unitrition
Інженерний посібник з інтеграції державних баз харчування в Next.js 16 та Headless WordPress: серверне проксіювання API, розрахунок Хлібних Одиниць та ізоляція даних у Supabase RLS за стандартами HIPAA/GDPR.
1. Резюме та висновок Bottom Line Up Front (BLUF)
Цифрові медичні платформи та сервіси персоналізованого харчування спираються на масштабні державні довідкові бази, такі як USDA FoodData Central API Міністерства сільського господарства США, що містить сотні тисяч продуктів. Проте багато команд припускаються критичної помилки, надсилаючи запити до державних API безпосередньо з клієнтського JavaScript у браузері.
Прямі запити з браузера створюють серйозні загрози: приватні API-ключі легко перехоплюються через вкладку Network, суворі федеральні ліміти (1 000 запитів/годину) блокують користувачів помилками HTTP 429 Too Many Requests, а затримка відповіді державних серверів (800мс - 2 000мс) руйнує показники Core Web Vitals.
У проєкті Unitrition (unitrition.info) ми спроєктували захищену серверну архітектуру Edge Proxy на базі Next.js 16 App Router. Цей пайплайн нормалізує сотні розрізнених форматів сирих даних у суворі TypeScript-моделі, здійснює детермінований розрахунок Хлібних Одиниць (ХО) для пацієнтів із цукровим діабетом 1 та 2 типу, кешує запити на edge з P95 затримкою 28мс (stale-while-revalidate) та надійно ізолює медичні профілі користувачів у Supabase PostgreSQL з Row Level Security (RLS) відповідно до стандартів HIPAA та GDPR.
Швидка матриця рішень: архітектури інтеграції клінічних API
| Архітектурний параметр | Прямий запит до USDA з браузера | Некешований серверний проксі | Пайплайн нормалізації Unitrition на Edge |
|---|---|---|---|
| P95 Затримка відповіді | 850мс - 1800мс (затримка API) | 420мс - 900мс (запит до сервера) | 28мс (Кешування Edge SWR) |
| Ризик витоку API-ключа | 100% (Перехоплення в браузері) | 0% (Захищене середовище) | 0% (Захищене середовище Edge) |
| Однорідність схеми даних | 0% (Неузгоджений JSON) | Часткова (Ручні перевірки) | 100% Сувора типізація TypeScript |
| Помилки лімітів 429 | 14.8% під час сплесків | 2.1% (Спільна IP сервера) | 0.00% (Буферний захист Edge) |
| Ізоляція даних за HIPAA | Ризиковано (Спільне сховище) | Ризиковано (Спільна БД) | Гарантовано (Supabase RLS та декуплінг) |
2. Причини проблеми: державні дані та регуляторні вимоги HealthTech
Інтеграція клінічних та державних API пов'язана зі специфічними викликами, яких немає у звичайних інтернет-магазинах:
kJ чи kcal, вуглеводи за різницею чи додані цукри). Без серверної нормалізації клієнтський код перетворюється на хаос із перевірок.| Параметр | Прямий виклик USDA з браузера | Некешований серверний проксі | Edge-пайплайн Unitrition |
|---|---|---|---|
| P95 Latency відповіді | 850мс - 1 800мс | 420мс - 900мс | 28мс (Edge SWR кеш) |
| Ризик розкриття API-ключа | 100% (Сніфінг мережі) | 0% (Сховано на сервері) | 0% (Сховано на сервері) |
| Однорідність схеми даних | 0% (Хаотичний вкладений JSON) | Часткова | 100% Строгий TypeScript |
| Помилки 429 (Rate Limit) | 14.8% під час сплесків | 2.1% (Спільний IP сервера) | 0.00% (Буфер Edge кешу) |
| Ізоляція даних HIPAA | Ризикована (Спільне сховище) | Ризикована | Гарантована (Supabase RLS) |
3. Архітектурний огляд: цикл Edge-проксі та нормалізації
Архітектура гарантує, що клієнти ніколи не спілкуються з державними серверами напряму, а редактори CMS не мають доступу до приватних медичних записів:
[ Клієнтський браузер: Пацієнт шукає продукт або планує раціон ]
│
▼ HTTPS GET (Debounced)
[ Next.js 16 Edge Route Handler: /api/nutrition/proxy ]
├── Крок 1: Перевірка лімітів та сесії користувача
├── Крок 2: Перевірка Edge кешу (stale-while-revalidate, < 28мс)
└── Крок 3: Захищений запит до USDA API (Секретний ключ не виходить назовні)
│
▼
[ Движок нормалізації нутрієнтів (TypeScript) ]
├── Калорії, загальні вуглеводи, клітковина, чисті вуглеводи, білки, жири
└── Детермінований розрахунок Хлібних Одиниць: ХО = Чисті вуглеводи (г) / 12
│
▼
[ Движок скорингу для 10 дієтичних протоколів ]
└── Оцінка відповідності: Кето, Діабет, Низький ГІ, Ренальна, Low-FODMAP
│
▼
[ Межа безпеки Zero-Trust ]
├── Публічні харчові дані: Edge CDN кеш (Vercel)
└── Медичні щоденники пацієнтів: Supabase PostgreSQL з Row Level Security (RLS)4. Практичний інженерний посібник
4.1. TypeScript-пайплайн нормалізації нутрієнтів
У Unitrition відповіді USDA приводяться до строгого інтерфейсу. Пропущені значення безпечно ініціалізуються нулями, а Хлібні Одиниці обчислюються математично точно:
export interface NormalizedNutrients {
calories: number
totalCarbohydrates: number
dietaryFiber: number
netCarbohydrates: number
sugars: number
protein: number
totalFat: number
breadUnits: number
}
export interface NormalizedFoodItem {
fdcId: number
description: string
foodCategory: string
servingSize: number
servingSizeUnit: string
nutrients: NormalizedNutrients
}
interface RawUsdaNutrient {
nutrientId?: number
nutrient?: { id: number }
value?: number
amount?: number
}
interface RawUsdaFoodItem {
fdcId: number
description: string
foodCategory?: string
servingSize?: number
servingSizeUnit?: string
foodNutrients?: RawUsdaNutrient[]
}
export function normalizeUsdaFoodItem(rawItem: RawUsdaFoodItem): NormalizedFoodItem {
const nutrientMap = new Map<number, number>()
for (const n of rawItem.foodNutrients || []) {
const id = n.nutrientId || n.nutrient?.id
const amount = n.value ?? n.amount ?? 0
if (id !== undefined) {
nutrientMap.set(id, amount)
}
}
const carbs = nutrientMap.get(1005) || 0
const fiber = nutrientMap.get(1079) || 0
const netCarbs = Math.max(0, carbs - fiber)
// Клінічна формула Хлібних Одиниць: 1 ХО = 10-12г засвоюваних вуглеводів
const breadUnits = Number((netCarbs / 12).toFixed(2))
return {
fdcId: rawItem.fdcId,
description: rawItem.description,
foodCategory: rawItem.foodCategory || 'Загальні продукти',
servingSize: rawItem.servingSize || 100,
servingSizeUnit: rawItem.servingSizeUnit || 'г',
nutrients: {
calories: Math.round(nutrientMap.get(1008) || 0),
totalCarbohydrates: Number(carbs.toFixed(1)),
dietaryFiber: Number(fiber.toFixed(1)),
netCarbohydrates: Number(netCarbs.toFixed(1)),
sugars: Number((nutrientMap.get(2000) || 0).toFixed(1)),
protein: Number((nutrientMap.get(1003) || 0).toFixed(1)),
totalFat: Number((nutrientMap.get(1004) || 0).toFixed(1)),
breadUnits,
},
}
}4.2. Next.js 16 Edge Route Handler (app/api/nutrition/proxy/route.ts)
Кінцева точка на edge приховує приватний ключ доступу, валідує параметри та налаштовує кешування відповідей:
import { NextRequest, NextResponse } from 'next/server'
import { normalizeUsdaFoodItem } from '@/lib/nutrition/normalizer'
export const runtime = 'edge'
export async function GET(request: NextRequest): Promise<NextResponse> {
const { searchParams } = new URL(request.url)
const query = searchParams.get('q')
if (!query || query.trim().length < 2) {
return NextResponse.json({ error: 'Пошуковий запит занадто короткий' }, { status: 400 })
}
const apiKey = process.env.USDA_FOODDATA_API_KEY
if (!apiKey) {
return NextResponse.json({ error: 'API-ключ не налаштовано' }, { status: 500 })
}
try {
const usdaUrl = `https://api.nal.usda.gov/fdc/v1/foods/search?query=${encodeURIComponent(
query
)}&pageSize=15&api_key=${apiKey}`
const upstreamRes = await fetch(usdaUrl, {
headers: { Accept: 'application/json' },
next: { revalidate: 86400 },
})
if (!upstreamRes.ok) {
return NextResponse.json({ error: 'Помилка шлюзу USDA' }, { status: 502 })
}
const data = await upstreamRes.json()
const normalizedFoods = (data.foods || []).map(normalizeUsdaFoodItem)
return NextResponse.json(
{ query, count: normalizedFoods.length, foods: normalizedFoods },
{
headers: {
'Cache-Control': 'public, s-maxage=86400, stale-while-revalidate=604800',
'Content-Type': 'application/json',
},
}
)
} catch (error) {
return NextResponse.json({ error: 'Збій проксі-обробника' }, { status: 500 })
}
}4.3. Політики Row Level Security (RLS) у Supabase PostgreSQL
Для гарантії відповідності HIPAA та GDPR щоденники прийому їжі захищені на рівні рядків бази даних:
-- Увімкнення захисту рядків для таблиці медичних щоденників
ALTER TABLE public.patient_meal_logs ENABLE ROW LEVEL SECURITY;
-- Пацієнт може переглядати лише власні записи
CREATE POLICY "Patients can view own meal logs"
ON public.patient_meal_logs
FOR SELECT
USING (auth.uid() = patient_id);
-- Пацієнт може створювати записи лише для свого ID
CREATE POLICY "Patients can insert own meal logs"
ON public.patient_meal_logs
FOR INSERT
WITH CHECK (auth.uid() = patient_id);
-- Пацієнт може редагувати та видаляти лише свої записи
CREATE POLICY "Patients can modify own meal logs"
ON public.patient_meal_logs
FOR UPDATE
USING (auth.uid() = patient_id)
WITH CHECK (auth.uid() = patient_id);5. Граничні сценарії, відмовостійкість та глибокий захист
stale-if-error=604800, завдяки чому пацієнти не втрачають доступ до розрахунку інсуліну.6. Архітектурні висновки та консультації
Інтеграція державних баз даних у цифрові медичні системи вимагає підходу Zero-Trust. Серверні edge-проксі, детермінована нормалізація даних та сувора ізоляція бази даних забезпечують швидкість 28мс і медичний рівень безпеки.
Розробляєте HealthTech-проєкт, платформу персоналізованого харчування чи медичний портал, що потребує відповідності стандартам HIPAA та захищеної інтеграції API? Ознайомтеся з нашими рішеннями в проєктах Unitrition та All Day Medical Care Clinic або зверніться до нашого AI-асистента для розрахунку архітектурного плану.
Де ця архітектура працює у моєму портфоліо
Ці інженерні рішення не є абстрактною теорією - вони повністю реалізовані та перевірені у наступних робочих продуктах:
Unitrition HealthTech Platform
Платформа персоналізованого харчування з інтеграцією USDA FoodData Central API, розрахунком Хлібних Одиниць, глікемічних кривих та 10 дієтичних протоколів.
All Day Medical Care Clinic
Високонадійний портал медичної клініки з доступністю для пацієнтів, безпечним записом на прийом та відповідністю стандартам HIPAA.
Плануєте міграцію стеку або розробку продукту?
Обговоріть архітектурні вимоги вашого проєкту з інтерактивним RAG AI-асистентом або зв’яжіться напряму для інженерної оцінки.
Інші інженерні статті
Next.js 16 проти Headless WordPress та Custom PHP: об’єктивний аналіз TCO, продуктивності та SEO (2026)
Інженерний аналіз архітектури, витрат на підтримку (TCO) та показників Google Core Web Vitals для Next.js 16, Headless WordPress та кастомного PHP.
Повний розбір архітектури Fullstack AI Lab: компіляція 1 135+ MDX-уроків за 90 секунд на Next.js 16 та Rust MDX-RS
Повний технічний та архітектурний розбір інтерактивної освітньої платформи Fullstack AI Lab: як ми прискорили статичну збірку у 14 разів (із 21.6 хв до 1.5 хв), створили браузерну WebAssembly-пісочницю WordPress, симулятор AI-співбесід, інтерактивні симулятори рантайму та аудіогенератор для NotebookLM.