AI-Agent/note-manager
1
0
Fork 0
Code Issues Pull Requests Activity

feat: 初始化云笔记项目

Browse Source 
功能特性:
- Markdown 编辑与实时预览
- 代码语法高亮
- 目录树形结构管理
- 图片粘贴上传
- Markdown 文件导入导出
- 笔记密码保护
- 前后端分离架构

技术栈:
- Go + Gin + GORM + SQLite
- 原生 HTML/CSS/JavaScript
- Highlight.js
This commit is contained in:
Note Manager
2026-05-08 15:07:22 +08:00
commit c8f03dd932
19 changed files with 4333 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
API.md
+585
View File
@@ -0,0 +1,585 @@
# 云笔记 API 文档
## 基础信息
- **Base URL**：`http://localhost:8080/api`
- **认证方式**：Cookie（后台管理接口需要）
- **默认密码**：`admin123`
---
## 公开接口
公开接口无需认证即可访问（只读）。
### 1. 获取笔记列表
获取分页的笔记列表。
**请求**
```
GET /api/notes
```
**Query 参数**
| 参数 | 类型 | 必填 | 说明 | 默认值 |
|------|------|------|------|--------|
| page | int | 否 | 页码 | 1 |
| page_size | int | 否 | 每页数量 | 20 |
| category | string | 否 | 按分类筛选 | - |
| tag | string | 否 | 按标签筛选 | - |
| pinned | bool | 否 | 只看置顶 | - |
| favorite | bool | 否 | 只看收藏 | - |
| parent_id | int | 否 | 按父目录筛选 | - |
**响应示例**
```json
{
"code": 0,
"message": "success",
"data": {
"items": [
{
"id": 1,
"title": "Go 语言教程",
"category": "技术",
"tags": "[\"Go\",\"编程\"]",
"is_pinned": true,
"is_favorite": false,
"is_folder": false,
"parent_id": 0,
"sort_order": 0,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
],
"total": 50,
"page": 1,
"page_size": 20,
"total_pages": 3
}
}
```
---
### 2. 获取单条笔记
根据 ID 获取笔记详情。
**请求**
```
GET /api/notes/:id
```
**路径参数**
| 参数 | 类型 | 说明 |
|------|------|------|
| id | int | 笔记 ID |
**响应示例**
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"title": "Go 语言教程",
"content": "# Go 语言\\n\\nGo 是一门简洁高效的编程语言。",
"category": "技术",
"tags": "[\"Go\",\"编程\"]",
"is_pinned": true,
"is_favorite": false,
"is_folder": false,
"parent_id": 0,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}
```
---
### 3. 搜索笔记
搜索标题和内容。
**请求**
```
GET /api/notes/search
```
**Query 参数**
| 参数 | 类型 | 必填 | 说明 | 默认值 |
|------|------|------|------|--------|
| q | string | 是 | 搜索关键词 | - |
| page | int | 否 | 页码 | 1 |
| page_size | int | 否 | 每页数量 | 20 |
**响应示例**
```json
{
"code": 0,
"message": "success",
"data": {
"items": [...],
"total": 5,
"page": 1,
"page_size": 20,
"total_pages": 1
}
}
```
---
### 4. 获取分类列表
获取所有分类。
**请求**
```
GET /api/categories
```
**响应示例**
```json
{
"code": 0,
"message": "success",
"data": ["技术", "生活", "工作", "随笔"]
}
```
---
### 5. 获取标签列表
获取所有标签。
**请求**
```
GET /api/tags
```
**响应示例**
```json
{
"code": 0,
"message": "success",
"data": ["Go", "Python", "JavaScript", "编程", "笔记"]
}
```
---
### 6. 获取树形结构
获取目录树形结构（包含目录和笔记）。
**请求**
```
GET /api/tree
```
**响应示例**
```json
{
"code": 0,
"message": "success",
"data": [
{
"id": 1,
"title": "技术文档",
"is_folder": true,
"children": [
{
"id": 2,
"title": "Go 语言教程",
"is_folder": false
}
]
},
{
"id": 3,
"title": "生活随笔",
"is_folder": false
}
]
}
```
---
## 管理接口
管理接口需要先登录，获取 Cookie 认证。
### 7. 登录
**请求**
```
POST /admin/login
```
**Body 参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| password | string | 是 | 管理员密码 |
**响应示例**
```json
{
"code": 0,
"message": "登录成功"
}
```
---
### 8. 登出
**请求**
```
POST /admin/logout
```
**响应示例**
```json
{
"code": 0,
"message": "已退出登录"
}
```
---
### 9. 检查认证状态
**请求**
```
GET /admin/auth
```
**响应示例**
```json
{
"authenticated": true
}
```
---
### 10. 创建笔记/目录
**请求**
```
POST /api/notes
```
**Body 参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| title | string | 是 | 标题 |
| content | string | 否 | 内容（Markdown） |
| category | string | 否 | 分类 |
| tags | string | string | 标签（JSON 数组格式） |
| is_folder | bool | 否 | 是否为文件夹 |
| is_pinned | bool | 否 | 是否置顶 |
| is_favorite | bool | 否 | 是否收藏 |
| parent_id | int | 否 | 父目录 ID |
| sort_order | int | 否 | 排序顺序 |
**请求示例**
```json
{
"title": "新建笔记",
"content": "# 我的笔记\\n\\n这是笔记内容",
"category": "技术",
"tags": "[\"笔记\",\"教程\"]",
"is_folder": false
}
```
**响应示例**
```json
{
"code": 0,
"message": "笔记创建成功",
"data": {
"id": 10
}
}
```
---
### 11. 更新笔记/目录
**请求**
```
PUT /api/notes/:id
```
**Body 参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| title | string | 否 | 标题 |
| content | string | 否 | 内容（Markdown） |
| category | string | 否 | 分类 |
| tags | string | 否 | 标签 |
| is_pinned | bool | 否 | 是否置顶 |
| is_favorite | bool | 否 | 是否收藏 |
| parent_id | int | 否 | 父目录 ID |
| sort_order | int | 否 | 排序顺序 |
**响应示例**
```json
{
"code": 0,
"message": "笔记更新成功"
}
```
---
### 12. 删除笔记/目录
**请求**
```
DELETE /api/notes/:id
```
**说明**：删除目录时会同时删除该目录下的所有子项。
**响应示例**
```json
{
"code": 0,
"message": "笔记删除成功"
}
```
---
## 响应状态码
| code | 说明 |
|------|------|
| 0 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权（需要登录） |
| 404 | 笔记不存在 |
| 500 | 服务器内部错误 |
---
## 密码保护笔记接口
### 访问密码保护的笔记
**请求**
```
POST /api/notes/:id/access
```
**Body 参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| password | string | 是 | 笔记访问密码 |
**响应示例**
```json
{
"code": 0,
"message": "访问成功",
"data": {
"id": 1,
"title": "受保护的笔记",
"content": "# 笔记内容..."
}
}
```
---
## 图片上传接口
### 上传图片
**请求**
```
POST /admin/api/upload
```
**说明**：需要登录认证。仅支持 jpg、png、gif、webp、bmp 格式，最大 5MB。
**Form 参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| image | file | 是 | 图片文件 |
**响应示例**
```json
{
"code": 0,
"message": "上传成功",
"data": {
"url": "/uploads/1234567890_abc123.png"
}
}
```
**图片访问**：上传后的图片通过 `/uploads/文件名` 访问。
---
## 导入导出接口
### 导出笔记为 Markdown
**请求**
```
GET /admin/api/export/:id
```
**说明**：需要登录认证。导出的文件包含 YAML front matter。
**响应**：下载 `.md` 文件，文件名以笔记标题命名。
---
### 导入 Markdown 文件
**请求**
```
POST /admin/api/import
```
**说明**：需要登录认证。仅支持 `.md` 文件。
**Form 参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | file | 是 | Markdown 文件 |
**响应示例**
```json
{
"code": 0,
"message": "导入成功",
"data": {
"id": 15,
"title": "导入的笔记标题"
}
}
```
---
## 错误响应示例
```json
{
"code": 401,
"message": "请先登录后台管理"
}
```
---
## 使用示例
### cURL
```bash
# 登录
curl -X POST http://localhost:8080/admin/login \
-d "password=admin123" \
-c cookies.txt
# 获取笔记列表
curl http://localhost:8080/api/notes
# 搜索笔记
curl "http://localhost:8080/api/notes/search?q=Go"
# 创建笔记（需要认证）
curl -X POST http://localhost:8080/api/notes \
-H "Content-Type: application/json" \
-b cookies.txt \
-d '{"title":"新笔记","content":"# 标题\\n\\n内容"}'
# 更新笔记（需要认证）
curl -X PUT http://localhost:8080/api/notes/1 \
-H "Content-Type: application/json" \
-b cookies.txt \
-d '{"title":"更新后的标题"}'
# 删除笔记（需要认证）
curl -X DELETE http://localhost:8080/api/notes/1 -b cookies.txt
```
### JavaScript (Fetch API)
```javascript
// 登录
await fetch('/admin/login', {
method: 'POST',
body: new URLSearchParams({ password: 'admin123' }),
credentials: 'include'
});
// 获取笔记列表
const res = await fetch('/api/notes');
const data = await res.json();
// 创建笔记
await fetch('/api/notes', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ title: '新笔记', content: '# 内容' }),
credentials: 'include'
});
```