Amansultan

Appearance

ADR-2: Правила формирования URL ​

Статус ​

Принято (04.09.2025)

Контекст ​

В проекте активно используются внешние хранилища (например, S3-совместимые сервисы) и генерация публичных ссылок.
Разные разработчики формировали URL по-разному: где-то базовый адрес имел завершающий /, где-то пути (slugs) не начинались с /, в итоге появлялись лишние // или битые ссылки.
Чтобы исключить ошибки и сделать правила единообразными, фиксируем конвенцию по работе с URL.

Решение ​

1. Базовый URL в .env ​

  • Всегда без завершающего слеша.
env
AWS_ENDPOINT=https://hb.kz-ast.bizmrg.com

2. Пути (slugs) в коде ​

  • Всегда с ведущим слешем.
txt
/amansultan-uploads/lms-certificates/685a54ab0c880eb771679c66/65e8a2b7423e94869577afbb.pdf

3. Сборка полного URL ​

  • Использовать URL из стандартной библиотеки Node.js.
  • Склеивать базу и путь безопасно.
ts
import { URL } from 'url';

const base = process.env.AWS_ENDPOINT!; // без завершающего '/'
const slug = '/path/to/resource.jpg';   // с ведущим '/'
const fullUrl = new URL(slug, base).toString();

// → https://hb.kz-ast.bizmrg.com/path/to/resource.jpg

4. Избегать // ​

  • При правильном формате переменных и путей лишние двойные слеши не появляются.

Пример:

env
AWS_ENDPOINT=https://hb.kz-ast.bizmrg.com
ts
const slug = '/amansultan-uploads/lms-certificates/.../file.pdf';
const url = new URL(slug, process.env.AWS_ENDPOINT!).toString();

// url = 'https://hb.kz-ast.bizmrg.com/amansultan-uploads/lms-certificates/.../file.pdf'

Последствия ​

  • ✅ Единый формат формирования URL.
  • ✅ Исключены ошибки с лишними слешами.
  • ✅ Код становится чище и понятнее.
  • ❌ Требуется дисциплина при объявлении .env и путей.