@hexlet/frontend-blog-server 0.0.0-stage → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +58 -2
- package/contract/main.tsp +286 -0
- package/contract/openapi.yaml +781 -0
- package/dist/bin/cli.d.ts +2 -0
- package/dist/bin/cli.js +63 -0
- package/dist/src/app.d.ts +6 -0
- package/dist/src/app.js +256 -0
- package/dist/src/generated/api.d.ts +911 -0
- package/dist/src/generated/api.js +5 -0
- package/dist/src/seed.d.ts +9 -0
- package/dist/src/seed.js +189 -0
- package/dist/src/state.d.ts +58 -0
- package/dist/src/state.js +81 -0
- package/package.json +60 -4
package/README.md
CHANGED
|
@@ -1,3 +1,59 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @hexlet/frontend-blog-server
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Готовый бэкенд для проекта «Блог». Писать его не нужно, вы подключаете пакет к своему фронтенду и работаете с настоящим API.
|
|
4
|
+
|
|
5
|
+
Сервер написан на Fastify 5 и держит данные в памяти. При каждом старте он загружает сид, поэтому после перезапуска блог возвращается к исходному состоянию.
|
|
6
|
+
|
|
7
|
+
## Запуск
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npx frontend-blog-server start # API на :8080
|
|
11
|
+
npx frontend-blog-server start -p 3000 # другой порт
|
|
12
|
+
npx frontend-blog-server start -s ./dist # API и собранный SPA из ./dist
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
С флагом `-s` сервер раздаёт сборку по `/` и API по `/api`, так что фронтенд и API живут на одном origin. На любой путь вне `/api` сервер отдаёт `index.html`, и клиентский роутинг работает при прямом заходе по адресу. Порт берётся из `-p`, затем из переменной `PORT`, иначе 8080.
|
|
16
|
+
|
|
17
|
+
## Контракт API
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npx frontend-blog-server contract # openapi.yaml и main.tsp в ./contract
|
|
21
|
+
npx frontend-blog-server contract api # в указанный каталог
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
`openapi.yaml` описывает все эндпоинты, тела запросов и ответов и коды ошибок.
|
|
25
|
+
|
|
26
|
+
## Типы
|
|
27
|
+
|
|
28
|
+
Пакет отдаёт типы, сгенерированные из `openapi.yaml` утилитой `openapi-typescript`. Они подходят для `openapi-fetch` и для своей обёртки над `fetch`.
|
|
29
|
+
|
|
30
|
+
```typescript
|
|
31
|
+
import type { components, paths } from "@hexlet/frontend-blog-server/schema";
|
|
32
|
+
|
|
33
|
+
type Article = components["schemas"]["Article"];
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Сид
|
|
37
|
+
|
|
38
|
+
| Что | Значение |
|
|
39
|
+
| --- | --- |
|
|
40
|
+
| Пользователи | `alice`, `bob`, `carol`, пароль у всех `password` |
|
|
41
|
+
| Категории | `frontend`, `backend`, `devops`, `design`, `career`, `news` |
|
|
42
|
+
| Статьи | 30 на русском и английском. У самой новой два комментария (ответ на ответ) и два лайка |
|
|
43
|
+
|
|
44
|
+
## Авторизация
|
|
45
|
+
|
|
46
|
+
`POST /api/users` (регистрация) и `POST /api/session` (вход) возвращают `token`. Его передают в заголовке `Authorization: Bearer <token>`. Токен живёт, пока работает сервер.
|
|
47
|
+
|
|
48
|
+
## Ошибки
|
|
49
|
+
|
|
50
|
+
Ошибка приходит телом `{ code, message }`. `code` машинный (`validation_error`, `unauthorized`, `forbidden`, `not_found`, `username_taken`, `invalid_credentials`), текст для пользователя фронтенд берёт из своих переводов по коду. `message` по-английски и нужен разработчику.
|
|
51
|
+
|
|
52
|
+
## Разработка пакета
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
npm ci
|
|
56
|
+
npm test # тесты API
|
|
57
|
+
npm run gen:types # src/generated/api.ts из contract/openapi.yaml, генератор идёт через npx с TypeScript 5
|
|
58
|
+
cd contract && npm ci && npm run compile # openapi.yaml из main.tsp
|
|
59
|
+
```
|
|
@@ -0,0 +1,286 @@
|
|
|
1
|
+
import "@typespec/http";
|
|
2
|
+
import "@typespec/openapi";
|
|
3
|
+
import "@typespec/openapi3";
|
|
4
|
+
|
|
5
|
+
using TypeSpec.Http;
|
|
6
|
+
using TypeSpec.OpenAPI;
|
|
7
|
+
|
|
8
|
+
@service(#{ title: "Blog API" })
|
|
9
|
+
@info(#{ version: "1.0.0" })
|
|
10
|
+
@server("http://localhost:8080", "Local development")
|
|
11
|
+
@doc("Токен из POST /api/session или POST /api/users в заголовке Authorization: Bearer <token>.")
|
|
12
|
+
namespace BlogApi;
|
|
13
|
+
|
|
14
|
+
// ---------- Ошибки ----------
|
|
15
|
+
|
|
16
|
+
@doc("""
|
|
17
|
+
Ошибка API. code — машинный код без текста на конкретном языке, сообщение для
|
|
18
|
+
пользователя фронтенд берёт из своих переводов по коду. message — подсказка
|
|
19
|
+
разработчику на английском.
|
|
20
|
+
""")
|
|
21
|
+
@example(#{ code: "validation_error", message: "title must not be empty" })
|
|
22
|
+
@error
|
|
23
|
+
model ApiError {
|
|
24
|
+
code:
|
|
25
|
+
| "validation_error"
|
|
26
|
+
| "unauthorized"
|
|
27
|
+
| "forbidden"
|
|
28
|
+
| "not_found"
|
|
29
|
+
| "username_taken"
|
|
30
|
+
| "invalid_credentials";
|
|
31
|
+
message: string;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
model BadRequest {
|
|
35
|
+
@statusCode _: 400;
|
|
36
|
+
@body body: ApiError;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
model Unauthorized {
|
|
40
|
+
@statusCode _: 401;
|
|
41
|
+
@body body: ApiError;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
model Forbidden {
|
|
45
|
+
@statusCode _: 403;
|
|
46
|
+
@body body: ApiError;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
model NotFound {
|
|
50
|
+
@statusCode _: 404;
|
|
51
|
+
@body body: ApiError;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
model Conflict {
|
|
55
|
+
@statusCode _: 409;
|
|
56
|
+
@body body: ApiError;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
// ---------- Пользователи и сессия ----------
|
|
60
|
+
|
|
61
|
+
@doc("Публичные данные пользователя.")
|
|
62
|
+
@example(#{ id: 1, username: "alice" })
|
|
63
|
+
model User {
|
|
64
|
+
id: int32;
|
|
65
|
+
username: string;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
@doc("Логин и пароль. username: 3–20 символов из латиницы, цифр, _ и -; password: от 6 символов.")
|
|
69
|
+
@example(#{ username: "alice", password: "password" })
|
|
70
|
+
model Credentials {
|
|
71
|
+
username: string;
|
|
72
|
+
password: string;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
@doc("Ответ на вход и регистрацию. token передаётся в заголовке Authorization: Bearer <token>.")
|
|
76
|
+
model Session {
|
|
77
|
+
token: string;
|
|
78
|
+
user: User;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
@doc("Профиль автора.")
|
|
82
|
+
model Profile {
|
|
83
|
+
...User;
|
|
84
|
+
articlesCount: int32;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
// ---------- Категории ----------
|
|
88
|
+
|
|
89
|
+
@doc("""
|
|
90
|
+
Категория. Список статический и задаётся сидом. slug стабилен и годится для URL и
|
|
91
|
+
ключей перевода, name — название по-английски.
|
|
92
|
+
""")
|
|
93
|
+
@example(#{ id: 1, slug: "frontend", name: "Frontend" })
|
|
94
|
+
model Category {
|
|
95
|
+
id: int32;
|
|
96
|
+
slug: string;
|
|
97
|
+
name: string;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
// ---------- Статьи ----------
|
|
101
|
+
|
|
102
|
+
@doc("Статья в ленте. body в ленте не приходит, только excerpt — начало текста без разметки Markdown.")
|
|
103
|
+
model ArticleSummary {
|
|
104
|
+
id: int32;
|
|
105
|
+
title: string;
|
|
106
|
+
excerpt: string;
|
|
107
|
+
category: Category;
|
|
108
|
+
author: User;
|
|
109
|
+
createdAt: utcDateTime;
|
|
110
|
+
likesCount: int32;
|
|
111
|
+
commentsCount: int32;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
@doc("""
|
|
115
|
+
Статья целиком. body — исходный Markdown, его рендерит фронтенд.
|
|
116
|
+
liked — поставил ли лайк текущий пользователь; для гостя всегда false.
|
|
117
|
+
""")
|
|
118
|
+
model Article {
|
|
119
|
+
...ArticleSummary;
|
|
120
|
+
body: string;
|
|
121
|
+
updatedAt: utcDateTime;
|
|
122
|
+
liked: boolean;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
@doc("Страница ленты.")
|
|
126
|
+
model ArticlePage {
|
|
127
|
+
items: ArticleSummary[];
|
|
128
|
+
page: int32;
|
|
129
|
+
perPage: int32;
|
|
130
|
+
total: int32;
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
@doc("Данные для создания статьи. title: 1–120 символов, body: непустой.")
|
|
134
|
+
model ArticleInput {
|
|
135
|
+
title: string;
|
|
136
|
+
body: string;
|
|
137
|
+
categoryId: int32;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
@doc("Правка статьи: передаются только меняющиеся поля.")
|
|
141
|
+
model ArticlePatch {
|
|
142
|
+
title?: string;
|
|
143
|
+
body?: string;
|
|
144
|
+
categoryId?: int32;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
// ---------- Комментарии ----------
|
|
148
|
+
|
|
149
|
+
@doc("""
|
|
150
|
+
Комментарий. Список приходит плоским, по возрастанию createdAt; дерево фронтенд
|
|
151
|
+
собирает сам по parentId. parentId = null у ответа на саму статью.
|
|
152
|
+
""")
|
|
153
|
+
model Comment {
|
|
154
|
+
id: int32;
|
|
155
|
+
body: string;
|
|
156
|
+
parentId: int32 | null;
|
|
157
|
+
author: User;
|
|
158
|
+
createdAt: utcDateTime;
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
@doc("Новый комментарий. parentId — комментарий той же статьи, на который это ответ.")
|
|
162
|
+
model CommentInput {
|
|
163
|
+
body: string;
|
|
164
|
+
parentId?: int32 | null;
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
@doc("Состояние лайка после изменения.")
|
|
168
|
+
model LikeState {
|
|
169
|
+
liked: boolean;
|
|
170
|
+
likesCount: int32;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
// ---------- Маршруты ----------
|
|
174
|
+
|
|
175
|
+
@route("/api/health")
|
|
176
|
+
@tag("System")
|
|
177
|
+
interface Health {
|
|
178
|
+
@get check(): { status: "ok" };
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
@route("/api/users")
|
|
182
|
+
@tag("Users")
|
|
183
|
+
interface Users {
|
|
184
|
+
@doc("Регистрация. Сразу возвращает сессию.")
|
|
185
|
+
@post
|
|
186
|
+
signup(@body body: Credentials): {
|
|
187
|
+
@statusCode _: 201;
|
|
188
|
+
@body body: Session;
|
|
189
|
+
} | BadRequest | Conflict;
|
|
190
|
+
|
|
191
|
+
@doc("Профиль автора по имени.")
|
|
192
|
+
@get
|
|
193
|
+
@route("/{username}")
|
|
194
|
+
profile(@path username: string): Profile | NotFound;
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
@route("/api/session")
|
|
198
|
+
@tag("Session")
|
|
199
|
+
interface SessionRoutes {
|
|
200
|
+
@doc("Вход.")
|
|
201
|
+
@post
|
|
202
|
+
login(@body body: Credentials): Session | BadRequest | Unauthorized;
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
@route("/api/me")
|
|
206
|
+
@tag("Session")
|
|
207
|
+
interface Me {
|
|
208
|
+
@doc("Текущий пользователь по токену.")
|
|
209
|
+
@get
|
|
210
|
+
@useAuth(BearerAuth)
|
|
211
|
+
me(): User | Unauthorized;
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
@route("/api/categories")
|
|
215
|
+
@tag("Categories")
|
|
216
|
+
interface Categories {
|
|
217
|
+
@get list(): Category[];
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
@route("/api/articles")
|
|
221
|
+
@tag("Articles")
|
|
222
|
+
interface Articles {
|
|
223
|
+
@doc("Лента, новые статьи первыми.")
|
|
224
|
+
@get
|
|
225
|
+
list(
|
|
226
|
+
@query page?: int32 = 1,
|
|
227
|
+
@doc("От 1 до 50.") @query perPage?: int32 = 10,
|
|
228
|
+
@doc("slug категории.") @query category?: string,
|
|
229
|
+
@doc("username автора.") @query author?: string,
|
|
230
|
+
): ArticlePage | BadRequest;
|
|
231
|
+
|
|
232
|
+
@get
|
|
233
|
+
@route("/{id}")
|
|
234
|
+
@doc("С токеном поле liked показывает лайк текущего пользователя.")
|
|
235
|
+
@useAuth(BearerAuth | NoAuth)
|
|
236
|
+
read(@path id: int32): Article | NotFound;
|
|
237
|
+
|
|
238
|
+
@post
|
|
239
|
+
@useAuth(BearerAuth)
|
|
240
|
+
create(@body body: ArticleInput): {
|
|
241
|
+
@statusCode _: 201;
|
|
242
|
+
@body body: Article;
|
|
243
|
+
} | BadRequest | Unauthorized;
|
|
244
|
+
|
|
245
|
+
@doc("Правка. Доступна только автору.")
|
|
246
|
+
@patch
|
|
247
|
+
@route("/{id}")
|
|
248
|
+
@useAuth(BearerAuth)
|
|
249
|
+
update(@path id: int32, @body body: ArticlePatch): Article
|
|
250
|
+
| BadRequest
|
|
251
|
+
| Unauthorized
|
|
252
|
+
| Forbidden
|
|
253
|
+
| NotFound;
|
|
254
|
+
|
|
255
|
+
@doc("Удаление вместе с комментариями и лайками. Доступно только автору.")
|
|
256
|
+
@delete
|
|
257
|
+
@route("/{id}")
|
|
258
|
+
@useAuth(BearerAuth)
|
|
259
|
+
remove(@path id: int32): {
|
|
260
|
+
@statusCode _: 204;
|
|
261
|
+
} | Unauthorized | Forbidden | NotFound;
|
|
262
|
+
|
|
263
|
+
@get
|
|
264
|
+
@route("/{id}/comments")
|
|
265
|
+
comments(@path id: int32): Comment[] | NotFound;
|
|
266
|
+
|
|
267
|
+
@post
|
|
268
|
+
@route("/{id}/comments")
|
|
269
|
+
@useAuth(BearerAuth)
|
|
270
|
+
comment(@path id: int32, @body body: CommentInput): {
|
|
271
|
+
@statusCode _: 201;
|
|
272
|
+
@body body: Comment;
|
|
273
|
+
} | BadRequest | Unauthorized | NotFound;
|
|
274
|
+
|
|
275
|
+
@doc("Поставить лайк. Повторный вызов ничего не меняет.")
|
|
276
|
+
@put
|
|
277
|
+
@route("/{id}/like")
|
|
278
|
+
@useAuth(BearerAuth)
|
|
279
|
+
like(@path id: int32): LikeState | Unauthorized | NotFound;
|
|
280
|
+
|
|
281
|
+
@doc("Снять лайк. Повторный вызов ничего не меняет.")
|
|
282
|
+
@delete
|
|
283
|
+
@route("/{id}/like")
|
|
284
|
+
@useAuth(BearerAuth)
|
|
285
|
+
unlike(@path id: int32): LikeState | Unauthorized | NotFound;
|
|
286
|
+
}
|