# webServer

**Repository Path**: norixln/web-server

## Basic Information

- **Project Name**: webServer
- **Description**: 小程序web端口 初代目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-03-31
- **Last Updated**: 2026-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Web Server

基于 [go-zero](https://github.com/zeromicro/go-zero) 构建的电商后端服务，提供用户认证、商品管理、订单管理等核心能力。

## 技术栈

- **框架**: go-zero v1.8.2 (REST API + JWT)
- **数据库**: MySQL + GORM v1.25.12
- **API 定义**: goctl API 定义语言 (`.api`)
- **密码安全**: bcrypt
- **部署**: Go 1.24+

## 项目结构

```
.
├── desc/api/               # API 定义文件
│   ├── common/             # 公共类型 (分页、通用响应等)
│   ├── order/              # 订单与商品服务接口定义
│   └── user/               # 用户服务接口定义
├── database/               # 数据库连接与迁移
├── etc/                    # 配置文件
├── internal/
│   ├── config/             # 应用配置
│   ├── handler/            # HTTP Handler (由 goctl 生成)
│   ├── logic/              # 业务逻辑层
│   ├── middleware/         # 中间件 (CORS / Log / Admin)
│   ├── model/              # GORM 数据模型
│   ├── repository/         # 数据访问层 (DAO)
│   ├── svc/                # 服务上下文
│   ├── types/              # 请求/响应结构体 (由 goctl 生成)
│   └── utils/              # 工具函数 (JWT 等)
├── web.go                  # 服务入口
└── go.mod
```

## 快速开始

### 1. 环境准备

- Go 1.24+
- MySQL 5.7+
- 安装 goctl:
  ```bash
  go install github.com/zeromicro/go-zero/tools/goctl@latest
  ```

### 2. 数据库配置

编辑 `etc/web.yaml`：

```yaml
Database:
  Mysql:
    DataSource: root:123456@tcp(localhost:3306)/webserver?charset=utf8mb4&parseTime=true&loc=Asia%2FShanghai
```

数据库首次启动时会自动执行 `AutoMigrate`，创建以下表：
- `users` — 用户表
- `products` — 商品表
- `orders` — 订单表
- `order_items` — 订单商品明细表

### 3. 编译与运行

```bash
# 开发模式
 go run web.go -f etc/web.yaml

# 编译
 go build -o web.exe web.go

# Linux 后台运行
 nohup ./web &
```

服务默认监听 `0.0.0.0:8888`。

## 核心功能

### 用户模块

| 接口 | 方法 | 路径 | 权限 |
|------|------|------|------|
| 用户登录 | POST | `/v1/auth/login` | 公开 |
| 用户注册 | POST | `/v1/auth/register` | 公开 |
| 获取个人信息 | GET | `/v1/user/profile` | JWT |
| 更新个人信息 | PUT | `/v1/user/profile` | JWT |
| 获取用户列表 | GET | `/v1/user/list` | **管理员** |
| 根据ID获取用户 | GET | `/v1/user/:id` | **管理员** |

### 商品模块

| 接口 | 方法 | 路径 | 权限 |
|------|------|------|------|
| 商品列表 | GET | `/v1/products` | 公开 |
| 商品详情 | GET | `/v1/products/:id` | 公开 |
| 创建商品 | POST | `/v1/products` | **管理员** |
| 更新商品 | PUT | `/v1/products/:id` | **管理员** |

### 订单模块

| 接口 | 方法 | 路径 | 权限 |
|------|------|------|------|
| 创建订单 | POST | `/v1/orders` | JWT |
| 订单详情 | GET | `/v1/orders/:id` | JWT (本人/管理员) |
| 我的订单 | GET | `/v1/orders/my` | JWT |
| 取消订单 | DELETE | `/v1/orders/:id/cancel` | JWT (本人/管理员) |
| 查看用户订单 | GET | `/v1/orders/user/:user_id` | **管理员** |
| 更新订单状态 | PATCH | `/v1/orders/:id/status` | **管理员** |

## 订单状态机

```
待支付 (0) ──→ 已支付 (1) ──→ 已发货 (2) ──→ 已完成 (3)
     │              │
     └──────────────┘
            ↓
      已取消 (4)
```

- 仅允许**合法的状态流转**，非法跳转会被拒绝
- 取消订单时，系统会**自动回滚商品库存**

## 权限设计

- **普通用户 (Role=0)**: 只能操作自己的订单和个人信息
- **管理员 (Role=1)**: 可以管理商品、查看所有用户订单、修改任意订单状态

JWT Payload 中包含 `userId` 和 `role`，`AdminMiddleware` 会校验管理员权限。

## 代码生成

当修改 `.api` 文件后，执行以下命令重新生成 `types`、`handler`、`routes`：

```bash
goctl api go -api desc/main.api -dir .
```

> 注意：goctl 不会覆盖已存在的 `logic` 和 `handler` 文件，需要手动同步类型变更。

## 配置文件说明

`etc/web.yaml`：

```yaml
Name: "webserver"
Host: 0.0.0.0
Port: 8888
WebPath: "./web/static"

Database:
  Mysql:
    DataSource: root:123456@tcp(localhost:3306)/webserver?charset=utf8mb4&parseTime=true&loc=Asia%2FShanghai

Auth:
  AccessSecret: "ae0536f9-6450-4606-8e13-5a19ed505da0"
  AccessExpire: 3600  # Token 有效期，单位秒
```

## 开发规范

1. **API 定义先行**: 所有接口变更先在 `desc/api/` 下的 `.api` 文件中定义，再执行 `goctl` 生成代码
2. **分层清晰**: Handler → Logic → Repository → Model，禁止跨层直接调用
3. **事务安全**: 涉及多个表修改的操作（如下单、取消订单）必须在事务中完成
4. **权限校验**: 敏感操作在 Logic 层校验用户身份和角色，不要只依赖路由中间件

## 许可证

MIT