# markdown-notes

**Repository Path**: cutecuteyu/markdown-notes

## Basic Information

- **Project Name**: markdown-notes
- **Description**: markdown笔记软件
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-29
- **Last Updated**: 2026-04-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Markdown 笔记应用

一个功能完整的 Markdown 笔记应用，前端基于 **Vue 3 + Vite** 构建，后端基于 **Go + Gin** 框架开发，使用 JSON 文件持久化存储。

---

## 目录

- [功能特性](#功能特性)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
  - [环境要求](#环境要求)
  - [安装步骤](#安装步骤)
  - [启动服务](#启动服务)
- [API 文档](#api-文档)
- [部署](#部署)
- [架构说明](#架构说明)
  - [后端架构](#后端架构)
  - [前端架构](#前端架构)
  - [数据流](#数据流)

---

## 功能特性

- **Markdown 编辑与实时预览** — 支持标题、粗体、斜体、代码块、链接、列表、引用等常用 Markdown 语法
- **工具栏快捷插入** — 一键插入 Markdown 语法标记，无需记忆语法
- **自动保存** — 输入停止 2 秒后自动保存，并显示"保存中... / 已保存"状态反馈
- **笔记搜索** — 按标题和内容同时搜索，实时过滤
- **全中文界面** — 所有界面文本、提示、错误信息均为中文
- **RESTful API** — 完整的 CRUD 接口，返回标准 JSON
- **双模式部署** — 开发模式支持前后端分离热更新，生产模式可单端口部署

---

## 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| 前端框架 | Vue 3 (Composition API) | 使用 `<script setup>` + 组合式函数 |
| 构建工具 | Vite 5 | 开发服务器支持 HMR 热更新 |
| Markdown 渲染 | marked | 将 Markdown 文本渲染为 HTML |
| 后端框架 | Go + Gin | 高性能 HTTP 框架 |
| 数据存储 | JSON 文件 | 本地文件系统持久化，无需数据库 |
| 数据模型 | UUID v4 | 使用 google/uuid 生成唯一标识 |

---

## 项目结构

```
markdown-notes/
├── backend/                          # Go 后端服务
│   ├── main.go                       # 入口文件（路由组装、服务启动）
│   ├── go.mod                        # Go 模块定义
│   ├── go.sum                        # 依赖校验文件
│   ├── handlers/
│   │   └── notes.go                  # HTTP 请求处理层
│   ├── middleware/
│   │   └── cors.go                   # CORS 跨域中间件
│   ├── models/
│   │   └── note.go                   # 数据模型定义
│   └── storage/
│       ├── store.go                  # 存储接口定义（抽象层）
│       └── json_store.go             # JSON 文件存储实现
│
├── frontend/                         # Vue 3 前端应用
│   ├── index.html                    # HTML 入口
│   ├── package.json                  # 依赖声明
│   ├── vite.config.js                # Vite 配置（含 API 代理）
│   └── src/
│       ├── main.js                   # Vue 应用入口
│       ├── style.css                 # 全局样式
│       ├── config.js                 # 应用配置（API 地址等）
│       ├── api/
│       │   └── index.js              # API 客户端（封装 fetch）
│       ├── composables/
│       │   └── useNotes.js           # 笔记业务逻辑组合式函数
│       ├── components/
│       │   ├── NoteList.vue          # 侧边栏笔记列表组件
│       │   └── NoteEditor.vue        # 笔记编辑器组件
│       └── App.vue                   # 根组件（布局层）
│
└── README.md                         # 本文件
```

---

## 快速开始

### 环境要求

- **Go** 1.21 或更高版本（[下载](https://go.dev/dl/)）
- **Node.js** 18 或更高版本（[下载](https://nodejs.org/)）
- **npm** 9 或更高版本（随 Node.js 一起安装）

### 安装步骤

1. 克隆项目并进入目录：

   ```bash
   cd markdown-notes
   ```

2. 安装后端依赖：

   ```bash
   cd backend
   go mod download
   cd ..
   ```

3. 安装前端依赖：

   ```bash
   cd frontend
   npm install
   cd ..
   ```

### 启动服务

**开发模式**（推荐，支持前端热更新）：

需要打开两个终端窗口分别运行后端和前端。

终端 1 — 启动后端服务（端口 8080）：

```bash
cd backend
go run .
```

终端 2 — 启动前端开发服务器（端口 5173）：

```bash
cd frontend
npm run dev
```

然后浏览器打开 **http://localhost:5173** 即可使用。

> 前端 Vite 开发服务器已配置 proxy，`/api/*` 的请求会自动转发到后端 `http://localhost:8080`，无需额外配置。

**生产模式**（单端口部署）：

```bash
cd frontend
npm run build          # 构建前端产物到 dist/
cd ../backend
go run .               # 后端自动托管前端静态文件
```

浏览器打开 **http://localhost:8080** 即可使用，无需启动前端开发服务器。

---

## API 文档

所有 API 端点均以 `/api` 为前缀，请求和响应均为 JSON 格式。

### 笔记模型

```json
{
  "id": "uuid-字符串",
  "title": "笔记标题",
  "content": "Markdown 格式的内容",
  "created_at": "2026-04-29T00:00:00+08:00",
  "updated_at": "2026-04-29T00:00:00+08:00"
}
```

### 接口列表

| 方法 | 路径 | 说明 | 请求体 | 响应 |
|------|------|------|--------|------|
| GET | `/api/notes` | 获取所有笔记 | — | `{"notes": [...]}` |
| GET | `/api/notes/:id` | 获取单个笔记 | — | 笔记对象 |
| POST | `/api/notes` | 创建笔记 | `{"title": "必填", "content": "可选"}` | 新笔记对象 |
| PUT | `/api/notes/:id` | 更新笔记 | `{"title": "可选", "content": "可选"}` | 更新后的笔记对象 |
| DELETE | `/api/notes/:id` | 删除笔记 | — | `{"message": "笔记已删除"}` |

### 状态码

- **200** — 请求成功
- **201** — 创建成功
- **400** — 请求参数错误（如标题为空、JSON 格式错误）
- **404** — 笔记不存在
- **500** — 服务器内部错误

---

## 部署

### 构建生产版本

```bash
# 构建前端
cd frontend
npm run build

# 构建后端可执行文件
cd ../backend
go build -o notes-app .

# 运行（Windows）
notes-app.exe

# 运行（Linux/macOS）
./notes-app
```

构建后，后端二进制文件会自动从 `../frontend/dist/` 加载前端静态文件，实现单端口部署。

### 自定义端口

修改 `backend/main.go` 中的端口号：

```go
r.Run(":8080")  // 将 8080 改为你需要的端口
```

---

## 架构说明

### 后端架构

后端采用分层架构，各层职责明确、单向依赖：

```
main.go (路由组装 / 启动)
  │
  ├──→ middleware/cors.go (跨域中间件)
  │
  └──→ handlers/notes.go (HTTP 请求处理)
         │                   依赖 Store 接口，不依赖具体实现
         ↓
       storage/store.go (Store 接口)
         ↑                   
       storage/json_store.go (JSON 文件实现)
         │
         └──→ models/note.go (数据模型)
```

**关键设计：** handlers 层通过 `storage.Store` **接口**（而非具体类型）访问数据，使得存储后端可被替换而不影响业务逻辑。例如切换到 MySQL 只需要新建一个实现 `Store` 接口的 `MySQLStore`。

### 前端架构

前端采用 Vue 3 Composition API 分层设计：

```
App.vue (布局层：拼接组件)
  │
  ├──→ composables/useNotes.js (业务逻辑层：状态管理 + CRUD)
  │       │
  │       └──→ api/index.js (网络层：封装 HTTP 请求)
  │               │
  │               └──→ config.js (配置层：API 地址、常量)
  │
  ├──→ components/NoteList.vue (UI 组件：侧边栏列表)
  │
  └──→ components/NoteEditor.vue (UI 组件：编辑器)
```

**关键设计：** 业务逻辑全部提取到 `useNotes` 组合式函数中，App.vue 只做组件拼接。UI 组件通过 props 接收数据、通过 emit 发送事件，不直接修改数据。

### 数据流

```
用户操作 → Vue 组件 (emit event) → useNotes (业务逻辑)
                                          ↓
                                    noteApi (HTTP 请求)
                                          ↓
                               Go 后端 Gin API (handlers)
                                          ↓
                                    JSONStore (读/写文件)
                                          ↓
                                    data/notes.json
```

自动保存流程：

1. 用户在编辑器中输入
2. 等待 2 秒无新输入，触发自动保存
3. NoteEditor 发送 `save` 事件给父组件
4. App.vue 调用 `useNotes().saveNote()`
5. `saving` 置为 `true`，显示"保存中..."
6. 调用 `noteApi.update()` 发送 PUT 请求
7. 后端更新 JSON 文件并返回新数据
8. `saving` 置为 `false`，显示"已保存"

---

## 许可证

MIT