112 lines
4.5 KiB
Markdown
112 lines
4.5 KiB
Markdown
# Nestly
|
||
|
||
Nestly 是一個以 Go 打造的房地產系統。後端使用 [chi](https://github.com/go-chi/chi) 作為 HTTP 路由器，網頁介面不依賴任何前端框架，直接以 Go 標準庫 `html/template` 進行 server-side rendering（SSR），樣式採用 [Tailwind CSS](https://tailwindcss.com)（standalone CLI 建置，無需 Node.js）。
|
||
|
||
## 特色
|
||
|
||
- **輕量技術棧**：chi 路由器、`html/template` 模板引擎與 GORM，不引入前端打包工具或 JavaScript 框架
|
||
- **Server-side rendering**：頁面由後端直接輸出完整 HTML，first paint 快、SEO 友善
|
||
- **Tailwind CSS**：以 standalone CLI 掃描模板產生最小化的 CSS，模板與靜態資源透過 `go:embed` 內嵌，部署只需單一執行檔
|
||
- **中介軟體架構**：利用 chi 內建的 middleware（logger、recoverer 等）與自訂 middleware 處理日誌、錯誤還原與驗證
|
||
- **巢狀路由**：以 chi 的 `Route` 組織資源導向的 URL 結構
|
||
|
||
## 技術棧
|
||
|
||
| 項目 | 說明 |
|
||
|------|------|
|
||
| 語言 | Go 1.26+ |
|
||
| 路由 | [chi v5](https://github.com/go-chi/chi) |
|
||
| 模板 | 標準庫 `html/template`（`go:embed` 內嵌） |
|
||
| 樣式 | [Tailwind CSS](https://tailwindcss.com) v4（standalone CLI 建置） |
|
||
| ORM | [GORM](https://gorm.io)（gorm.io/gorm） |
|
||
| 資料庫 | SQLite（開發環境，[glebarez/sqlite](https://github.com/glebarez/sqlite) 純 Go driver；PostgreSQL 規劃中） |
|
||
| Session | HMAC-SHA256 簽名 cookie（`internal/auth`） |
|
||
|
||
## 快速開始
|
||
|
||
### 環境需求
|
||
|
||
- Go 1.26 以上
|
||
- Tailwind standalone CLI（已放在 `tools/tailwindcss`；或自行[下載](https://tailwindcss.com/blog/standalone-cli)對應平台的執行檔）
|
||
|
||
### 安裝與執行
|
||
|
||
```bash
|
||
# 取得專案
|
||
git clone <repository-url>
|
||
cd nestly
|
||
|
||
# 安裝依賴
|
||
go mod download
|
||
|
||
# 編譯 CSS 並執行
|
||
make css
|
||
make run
|
||
```
|
||
|
||
伺服器預設啟動於 `http://localhost:3000`，可透過環境變數調整：
|
||
|
||
| 環境變數 | 預設 | 說明 |
|
||
|----------|------|------|
|
||
| `PORT` | `3000` | 監聽埠號 |
|
||
| `DB_DSN` | `nestly.db` | SQLite 資料庫檔案路徑 |
|
||
| `SESSION_SECRET` | 開發用預設值（會印出警告） | session cookie 的 HMAC 簽章密鑰 |
|
||
| `COOKIE_SECURE` | `false` | 設為 `true` 時 cookie 僅經 HTTPS 傳送 |
|
||
|
||
首次啟動會自動建立示範帳號 **demo@nestly.test**（密碼 `nestly1234`），可直接至 `/login` 試用登入流程。
|
||
|
||
### Tailwind CSS 開發流程
|
||
|
||
- 來源檔：`web/static/src/input.css`；編譯產物：`web/static/css/app.css`（已列入版本控制，執行檔內嵌此檔）
|
||
- 修改模板中的 class 後執行 `make css` 重新編譯；開發時可用 `make watch` 自動重建
|
||
|
||
## 專案結構
|
||
|
||
```text
|
||
nestly/
|
||
├── main.go # 程式進入點：初始化資料庫、session 與路由
|
||
├── internal/
|
||
│ ├── auth/ # HMAC 簽名 cookie session
|
||
│ ├── handlers/ # HTTP handlers（每個資源一個檔案）
|
||
│ ├── models/ # 資料結構與資料存取
|
||
│ ├── storage/ # 資料庫連線
|
||
│ ├── templates/ # html/template 模板渲染邏輯
|
||
│ └── middleware/ # 自訂 chi middleware（規劃中）
|
||
├── web/
|
||
│ ├── web.go # go:embed 內嵌模板與靜態資源
|
||
│ ├── templates/ # HTML 模板（layout.html + pages/*.html）
|
||
│ └── static/ # 靜態資源（src/input.css → css/app.css）
|
||
├── tools/ # 開發工具（tailwindcss standalone CLI）
|
||
├── Makefile
|
||
├── go.mod
|
||
└── README.md
|
||
```
|
||
|
||
## 路由
|
||
|
||
目前完成與規劃中的路由：
|
||
|
||
| 方法 | 路徑 | 說明 |
|
||
|------|------|------|
|
||
| GET | `/` | 首頁（顯示登入狀態） |
|
||
| GET | `/login` | 登入頁面 |
|
||
| POST | `/login` | 登入（驗證成功建立 session） |
|
||
| POST | `/logout` | 登出（清除 session） |
|
||
| GET | `/properties` | 物件列表（支援搜尋、篩選、分頁，規劃中） |
|
||
| GET | `/properties/{id}` | 物件詳細資訊（規劃中） |
|
||
| GET | `/properties/new` | 新增物件表單（規劃中） |
|
||
| POST | `/properties` | 建立物件（規劃中） |
|
||
| GET | `/properties/{id}/edit` | 編輯物件表單（規劃中） |
|
||
| PUT | `/properties/{id}` | 更新物件（規劃中） |
|
||
| DELETE | `/properties/{id}` | 刪除物件（規劃中） |
|
||
|
||
## 開發
|
||
|
||
```bash
|
||
make css # 編譯 Tailwind CSS
|
||
make watch # 監看並自動重建 CSS
|
||
make run # 啟動開發伺服器
|
||
go vet ./... # 靜態檢查
|
||
make test # 執行測試
|
||
```
|