dsh/go_blog
1
0 Fork 0
forked from kevin/go_blog
Code Pull Requests Activity

docs: README 路由表同步 API 化（页面/API 分离 + API 约定章节）

Browse Source
This commit is contained in:
kevin
2026-08-27 20:08:11 +08:00
parent 7f0beb5b0c
commit 7d12167380
2 changed files with 57 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+45 -31
View File
@@ -224,57 +224,71 @@ go_blog/
|---|---|---|
| GET | `/` | 首页 |
| GET | `/search` | 搜索页 |
| GET | `/api/articles` | 文章列表 API（无限滚动） |
| GET | `/rss`、`/feed` | RSS 订阅 |
| GET | `/article/:slug` | 文章详情 |
| POST | `/article/:slug/comments` | 发表评论 |
| GET | `/rss`、`/feed` | RSS 订阅 |
| GET | `/login` | 登录页 |
| POST | `/login` | 提交登录 |
| GET | `/register` | 注册页 |
| POST | `/register` | 提交注册 |
| POST | `/logout` | 退出登录 |
| GET | `/uploads/*` | 静态文件（头像、附件等） |
### 公开 JSON API（`/api` 前缀）
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/articles` | 文章列表 API（无限滚动） |
| POST | `/api/auth/login` | 登录（限流锁定 429） |
| POST | `/api/auth/register` | 注册（用户名冲突 409） |
| POST | `/api/auth/logout` | 退出登录 |
| POST | `/api/article/:slug/comments` | 发表评论（校验错误 400） |
### 管理后台（需管理员权限）
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/admin` | 管理后台首页 |
| GET | `/admin/articles` | 文章列表 |
| GET/POST | `/admin/articles/new` | 新建文章 |
| GET/POST | `/admin/articles/:id/edit` | 编辑文章 |
| POST | `/admin/articles/:id/delete` | 删除文章 |
| POST | `/admin/articles/attachments` | 上传附件 |
| POST | `/admin/articles/attachments/:id/delete` | 删除附件 |
| GET | `/admin/articles/:id/attachments` | 附件列表 |
| GET | `/admin/articles/new` | 新建文章表单 |
| GET | `/admin/articles/:id/edit` | 编辑文章表单 |
| GET | `/admin/comments` | 评论管理 |
| POST | `/admin/comments/:id/approve` | 通过评论 |
| POST | `/admin/comments/:id/reject` | 拒绝评论 |
| POST | `/admin/comments/:id/delete` | 删除评论 |
| GET | `/admin/users` | 用户列表 |
| GET/POST | `/admin/users/new` | 新建用户 |
| GET/POST | `/admin/users/:id/edit` | 编辑用户 |
| POST | `/admin/users/:id/delete` | 删除用户 |
| GET | `/admin/users/new` | 新建用户表单 |
| GET | `/admin/users/:id/edit` | 编辑用户表单 |
| GET | `/admin/analytics/views` | 阅读统计 |
| GET/POST | `/admin/settings/site` | 站点设置 |
| GET/POST | `/admin/settings/navlinks` | 导航链接设置 |
| GET/POST | `/admin/settings/upload` | 上传设置 |
| GET/POST | `/admin/settings/download` | 下载设置 |
| GET/POST | `/admin/settings/comments` | 评论设置 |
| GET | `/admin/settings/site`、`/navlinks`、`/upload`、`/download`、`/comments` | 各设置页 |
管理 JSON API（仅管理员，均带 JSON 错误码 + HTTP 语义状态码）：
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/admin/articles` | 创建文章 |
| PUT/DELETE | `/api/admin/articles/:id` | 更新/删除文章 |
| POST | `/api/admin/articles/attachments` | 上传附件（multipart） |
| DELETE | `/api/admin/articles/attachments/:id` | 删除附件 |
| GET | `/api/admin/articles/:id/attachments` | 附件列表 |
| POST | `/api/admin/comments/:id/approve`、`/:id/reject`、`/:id/delete` | 评论审核操作 |
| POST/PUT/DELETE | `/api/admin/users`、`/:id` | 用户增改删（自禁/最后管理员均 403） |
| POST | `/api/admin/settings/site` | 站点设置（文本/URL/清除） |
| POST | `/api/admin/settings/site/favicon`、`/site/logo` | favicon/logo 上传（multipart） |
| POST | `/api/admin/settings/navlinks`、`/upload`、`/download`、`/comments` | 各设置保存（`action` 分发） |
### 个人中心（需登录）
| 方法 | 路径 | 说明 |
|---|---|---|
| GET/POST | `/profile` | 编辑个人信息 |
| POST | `/profile/avatar` | 上传头像 |
| GET | `/profile` | 编辑个人信息页 |
| POST | `/api/profile` | 保存资料（JSON，密码改密校验 400） |
| POST | `/api/profile/avatar` | 上传头像（multipart、JPEG 重编码） |
| GET | `/my/articles` | 我的文章列表 |
| GET/POST | `/my/articles/new` | 新建文章 |
| GET/POST | `/my/articles/:id/edit` | 编辑文章 |
| POST | `/my/articles/:id/delete` | 删除文章 |
| POST | `/my/articles/attachments` | 上传附件 |
| POST | `/my/articles/attachments/:id/delete` | 删除附件 |
| GET | `/my/articles/:id/attachments` | 附件列表 |
| GET | `/my/articles/new`、`/:id/edit` | 我的文章表单页 |
| POST/PUT/DELETE | `/api/my/articles`、`/:id` | 文章增改删（跨作者 404/403） |
| POST | `/api/my/articles/attachments` | 上传附件（multipart） |
| DELETE | `/api/my/articles/attachments/:id` | 删除附件 |
| GET | `/api/my/articles/:id/attachments` | 附件列表 |
### API 约定
- 成功：`{"ok": true, "redirect": "...", "data": {...}}`（`redirect` 为原 302 目标，前端 fetch 后跳转）
- 失败：`{"ok": false, "code": "<i18n 键>", "error": "<按请求语言翻译的文案>"}`；状态码：400 校验失败 / 401 未登录 / 403 无权限 / 404 不存在 / 409 冲突 / 429 限流锁定 / 500 服务错误
- 除文件上传（multipart）外请求体为 `application/json`；CSRF 通过 `X-CSRF-Token` 请求头传递
## 用户角色
TODO_API_REFACTOR.md
+12 -12
View File
@@ -18,21 +18,21 @@
- [x] 7. 认证 API：`auth.go` Login/Register/Logout JSON 化（429 限流、会话轮换保留）
- [x] 8. 认证模板：`login.html`/`register.html` 改 fetch + 错误 div `id`；base.html logout 改 fetch（logout-form 全局委托）
- [ ] 9. 评论 API：`comment.go` PostComment JSON 化（校验码复用 i18n 键）
- [ ] 10. 评论 API：`admin_comment.go` approve/reject/delete JSON 化
- [ ] 11. 评论模板：`article.html` 评论表单 fetch、`comment_list.html` 操作后 reload
- [ ] 12. 文章 CRUD API：`article.go`/`my_articles.go` 去 renderForm/Redirect 改 JSON（表单字段加 json tag）
- [ ] 13. 文章模板：`article_create.html`/`my_article_form.html`/`article_list.html`/`my_articles.html` 改 fetch（`easyMDE.value()`、`e.submitter`）
- [ ] 14. 用户 API：`admin_user.go` UserCreate/Update/Delete JSON 化（自防/最后管理员拦截改 403）
- [ ] 15. 用户模板：`user_form.html`/`user_list.html` 改 fetch
- [ ] 16. 设置 API：`settings.go` 5 组 save JSON 化；site favicon 拆出 `POST /api/admin/settings/site/favicon`
- [ ] 17. 设置模板：`settings_site`/`settings_navlinks`/`settings_upload`/`settings_download`/`settings_comment` 5 页改 fetch
- [ ] 18. 个人资料 API：`profile.go` UpdateProfile JSON 化（头像走 `/api/profile/avatar`）
- [ ] 19. 个人资料模板：`profile.html` 文本表单改 fetch
- [x] 9. 评论 API：`comment.go` PostComment JSON 化（校验码复用 i18n 键）
- [x] 10. 评论 API：`admin_comment.go` approve/reject/delete JSON 化
- [x] 11. 评论模板：`article.html` 评论表单 fetch、`comment_list.html` 操作后 reload
- [x] 12. 文章 CRUD API：`article.go`/`my_articles.go` 去 renderForm/Redirect 改 JSON（表单字段加 json tag）
- [x] 13. 文章模板：`article_create.html`/`my_article_form.html`/`article_list.html`/`my_articles.html` 改 fetch（`easyMDE.value()`、`e.submitter`）
- [x] 14. 用户 API：`admin_user.go` UserCreate/Update/Delete JSON 化（自防/最后管理员拦截改 403）
- [x] 15. 用户模板：`user_form.html`/`user_list.html` 改 fetch
- [x] 16. 设置 API：`settings.go` 5 组 save JSON 化；site favicon/logo 拆出 `POST /api/admin/settings/site/favicon|logo`
- [x] 17. 设置模板：`settings_site`/`settings_navlinks`/`settings_upload`/`settings_download`/`settings_comment` 5 页改 fetch（blogSettingsForm 委托）
- [x] 18. 个人资料 API：`profile.go` UpdateProfile JSON 化（头像走 `/api/profile/avatar`）
- [x] 19. 个人资料模板：`profile.html` 文本表单改 fetch
## 测试与收尾（high）
- [ ] 20. 新增 `handlers/api_test.go`：happy path / 校验码 / 401 / 403 / CSRF 头 / 429 / 409
- [x] 20. 新增 `handlers/api_test.go`：happy path / 校验码 / 401 / 403 / CSRF 头 / 429 / 409
- [ ] 21. 更新 `security_test.go`/`p2_validation_test.go`/`p3_upload_test.go`/`session_upload_security_test.go` 到新 URL 与 JSON 断言
- [ ] 22. `go build ./... && go vet ./... && go test ./...` 全绿；README 路由表同步