# go_server_demo

**Repository Path**: futurelei/go_server_demo

## Basic Information

- **Project Name**: go_server_demo
- **Description**: go语言开发服务端实现类似fastapi效果的示例教学代码，包含swagger后台。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-05
- **Last Updated**: 2026-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Go FastAPI Demo

一个类似 FastAPI 的 Go 后端项目示例，包含：
- Gin Web 框架
- Swagger API 文档
- RESTful API 示例
- 完整的工程目录结构

## 项目特点

- ✅ 使用 Gin 框架实现高性能 HTTP 服务
- ✅ 集成 Swagger UI 自动生成 API 文档
- ✅ 使用 validator 进行请求参数验证
- ✅ 规范的工程目录结构
- ✅ 提供 CRUD 示例接口
- ✅ 详细的注释和文档

## 工程结构

```
go_server/
├── cmd/                    # 命令入口
│   └── server/             # 主服务入口
│       └── main.go         # 程序主入口
├── internal/               # 内部代码（不对外暴露）
│   ├── api/                # API 控制器
│   │   ├── user.go         # 用户相关接口
│   │   └── health.go       # 健康检查接口
│   ├── model/              # 数据模型
│   │   └── user.go         # 用户模型
│   ├── service/            # 业务逻辑层
│   │   └── user_service.go # 用户服务
│   ├── repository/         # 数据访问层
│   │   └── user_repo.go    # 用户存储
│   └── config/             # 配置管理
│       └── config.go       # 配置读取
├── pkg/                    # 公共包（可对外复用）
│   └── response/           # 统一响应处理
│       └── response.go     # 响应封装
├── docs/                   # Swagger 文档（自动生成）
│   ├── docs.go             # Swagger 信息和模板
│   ├── swagger.json        # API 文档（JSON 格式）
│   └── swagger.yaml        # API 文档（YAML 格式）
├── scripts/                # 开发脚本
│   ├── install.sh          # 安装依赖脚本
│   ├── build.sh            # 编译脚本
│   ├── run.sh              # 启动脚本
│   ├── test.sh             # 测试脚本
│   └── clean.sh            # 清理脚本
├── test/                   # 测试用例
│   └── user_service_test.go # 用户服务测试
├── go.mod                  # Go 依赖管理
├── go.sum                  # 依赖校验
├── .gitignore              # Git 忽略配置
└── README.md               # 项目说明
```

## 目录职责说明

| 目录 | 职责 | 是否对外暴露 |
|------|------|-------------|
| `cmd/` | 命令行入口，程序启动点 | 否 |
| `internal/` | 内部业务逻辑，不对外暴露 | 否 |
| `internal/api/` | HTTP 控制器，处理请求响应 | 否 |
| `internal/model/` | 数据结构定义 | 否 |
| `internal/service/` | 业务逻辑处理 | 否 |
| `internal/repository/` | 数据访问抽象 | 否 |
| `internal/config/` | 配置管理 | 否 |
| `pkg/` | 可复用的公共组件 | 是 |
| `docs/` | API 文档 | 是 |
| `scripts/` | 开发脚本集合 | 是 |
| `test/` | 单元测试用例 | 是 |

## 环境要求

- Go 1.18+
- 无需额外数据库（本示例使用内存存储）

## 安装 Go 环境

### 在 Ubuntu/Debian 上安装

```bash
# 更新软件源
sudo apt-get update

# 安装 Go
sudo apt-get install -y golang-go

# 验证安装
go version
```

### 在 macOS 上安装

```bash
# 使用 Homebrew
brew install go

# 验证安装
go version
```

### 在 Windows 上安装

1. 下载安装包: https://go.dev/dl/
2. 运行安装程序
3. 配置环境变量

### 配置 Go 代理（国内用户推荐）

由于网络原因，国内用户建议配置 Go 模块代理：

```bash
# 临时设置（当前终端生效）
export GOPROXY=https://goproxy.cn,direct

# 永久设置（写入 ~/.bashrc 或 ~/.zshrc）
echo 'export GOPROXY=https://goproxy.cn,direct' >> ~/.bashrc
source ~/.bashrc
```

**可用的 Go 代理：**

| 代理地址 | 说明 |
|----------|------|
| `https://goproxy.cn` | 七牛云（国内推荐） |
| `https://goproxy.io` | 阿里云 |
| `https://mirrors.aliyun.com/goproxy/` | 阿里云镜像 |

## 快速开始

### 使用脚本一键安装和运行

```bash
# 安装依赖
./scripts/install.sh

# 编译项目
./scripts/build.sh

# 运行服务
./scripts/run.sh
```

### 手动安装与运行

#### 1. 安装依赖

```bash
go mod download
```

#### 2. 生成 Swagger 文档

**Swagger 文档由 swag 工具根据代码注解自动生成。**

```bash
# 安装 swag 工具
go install github.com/swaggo/swag/cmd/swag@latest

# 生成 Swagger 文档（在项目根目录执行）
swag init -g cmd/server/main.go -o docs
```

**自动生成的文件：**
- `docs/docs.go` - Swagger 信息和模板（Go 代码）
- `docs/swagger.json` - API 文档（JSON 格式）
- `docs/swagger.yaml` - API 文档（YAML 格式）

> **注意**：这些文件由 swag 自动生成，每次修改 API 或注解后需要重新运行 `swag init`

#### 3. 运行服务

```bash
go run cmd/server/main.go
```

## 开发脚本

项目提供了以下便捷脚本：

| 脚本 | 说明 | 命令 |
|------|------|------|
| `install.sh` | 安装依赖和工具 | `./scripts/install.sh` |
| `build.sh` | 编译项目（支持静态/动态链接） | `./scripts/build.sh [-d\|--dynamic]` |
| `run.sh` | 启动开发服务器（支持端口配置） | `./scripts/run.sh [-p <port>] [-i <host>]` |
| `test.sh` | 运行测试并生成覆盖率报告 | `./scripts/test.sh` |
| `clean.sh` | 清理构建产物 | `./scripts/clean.sh` |

### build.sh - 编译脚本

支持静态链接和动态链接两种模式：

```bash
# 默认静态链接（推荐，无外部依赖）
./scripts/build.sh

# 动态链接（更小体积，需要系统库）
./scripts/build.sh -d
./scripts/build.sh --dynamic

# 显式指定静态链接
./scripts/build.sh -s
./scripts/build.sh --static
```

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `-d, --dynamic` | 使用动态链接 | 否（默认静态） |
| `-s, --static` | 使用静态链接 | 是 |

**静态 vs 动态链接对比：**

| 特性 | 静态链接 | 动态链接 |
|------|----------|----------|
| 体积 | 较大 (~24MB) | 较小 (~25MB，本项目差异不大) |
| 依赖 | 无依赖，可直接运行 | 需要系统库支持 |
| 兼容性 | 跨发行版通用 | 可能受系统库版本影响 |
| 适用场景 | 生产环境、容器部署 | 开发调试 |

### run.sh - 启动脚本

支持配置绑定地址和端口：

```bash
# 默认启动（0.0.0.0:8080）
./scripts/run.sh

# 指定端口
./scripts/run.sh -p 9090
./scripts/run.sh --port 9090

# 指定绑定地址（仅本地访问）
./scripts/run.sh -i 127.0.0.1
./scripts/run.sh --host 127.0.0.1

# 同时指定地址和端口
./scripts/run.sh -i 127.0.0.1 -p 9090
```

| 参数 | 别名 | 说明 | 默认值 |
|------|------|------|--------|
| `-p` | `--port` | 服务器监听端口 | `8080` |
| `-i` | `--ip`, `--host` | 绑定地址 | `0.0.0.0` |

### test.sh - 测试脚本

```bash
# 运行所有测试并生成覆盖率报告
./scripts/test.sh
```

执行后会生成 `coverage.out` 和 `coverage.html` 文件，查看覆盖率报告：

```bash
# 查看覆盖率报告
cat coverage.out
# 或在浏览器中打开 coverage.html
```

### clean.sh - 清理脚本

```bash
# 清理构建产物和测试文件
./scripts/clean.sh
```

清理内容：
- `bin/` - 编译产物
- `coverage.out`, `coverage.html` - 测试覆盖率文件
- `*.log` - 日志文件
- Go 模块缓存

## 访问服务

- API 服务地址: `http://localhost:8080`
- Swagger UI: `http://localhost:8080/swagger/index.html`
- 健康检查: `http://localhost:8080/api/health`

## API 接口列表

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/health` | 健康检查 |
| GET | `/api/users` | 获取所有用户列表 |
| GET | `/api/users/:id` | 获取单个用户 |
| POST | `/api/users` | 创建新用户 |
| PUT | `/api/users/:id` | 更新用户信息 |
| DELETE | `/api/users/:id` | 删除用户 |

## API 使用示例

### 获取所有用户

```bash
curl http://localhost:8080/api/users
```

### 获取单个用户

```bash
curl http://localhost:8080/api/users/1
```

### 创建用户

```bash
curl -X POST http://localhost:8080/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe","email":"john@example.com","age":30}'
```

### 更新用户

```bash
curl -X PUT http://localhost:8080/api/users/1 \
  -H "Content-Type: application/json" \
  -d '{"name":"John Updated","email":"john.updated@example.com","age":31}'
```

### 删除用户

```bash
curl -X DELETE http://localhost:8080/api/users/1
```

## 响应格式

### 成功响应

```json
{
  "code": 200,
  "message": "success",
  "data": { ... }
}
```

### 错误响应

```json
{
  "code": 404,
  "message": "User not found",
  "data": null
}
```

## 开发说明

### 添加新接口步骤

1. 在 `internal/model/` 中定义数据结构
2. 在 `internal/repository/` 中实现数据访问
3. 在 `internal/service/` 中实现业务逻辑
4. 在 `internal/api/` 中定义路由和处理函数
5. 更新 `cmd/server/main.go` 注册路由
6. 重新生成 Swagger 文档

### 代码规范

- 使用 `go fmt` 格式化代码
- 使用 `go vet` 检查代码
- 使用 `golint` 检查代码风格

## License

MIT