# student-api

**Repository Path**: go_27/student-api

## Basic Information

- **Project Name**: student-api
- **Description**: No description available
- **Primary Language**: Go
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-30
- **Last Updated**: 2025-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Student API

#### 项目介绍
学生管理 API 服务是一个基于 Go 语言开发的 RESTful Web 服务，专门用于学生信息的管理。该项目采用现代化的软件架构设计，提供了完整的学生信息增删改查功能，具备高可用性和良好的扩展性。

#### 核心特性
- **完整的 CRUD 操作**: 支持学生信息的创建、查询、更新、删除
- **数据验证**: 使用 go-playground/validator 进行请求数据验证
- **优雅的错误处理**: 统一的错误响应格式和详细的错误信息
- **配置管理**: 支持 YAML 配置文件、环境变量和命令行参数
- **SQLite 数据库**: 轻量级嵌入式数据库，无需额外数据库服务
- **优雅关闭**: 支持信号处理的服务器优雅关闭机制
- **结构化日志**: 使用 slog 进行结构化日志记录

#### 技术栈
- **编程语言**: Go 1.21+
- **HTTP 框架**: 标准库 net/http
- **数据库**: SQLite3 (modernc.org/sqlite 驱动)
- **配置管理**: cleanenv + YAML
- **数据验证**: go-playground/validator/v10
- **日志系统**: log/slog

#### 软件架构设计
项目采用清晰的分层架构，遵循 Go 语言最佳实践：

- **配置层 (config)**: 统一的配置管理，支持多环境配置
- **数据层 (storage)**: 数据库操作封装，提供统一的存储接口
- **业务层 (handlers)**: HTTP 请求处理器，处理业务逻辑
- **模型层 (types)**: 数据模型定义和验证规则
- **工具层 (utils)**: 通用工具函数，如响应格式化

#### 主要功能模块

##### 1. 学生管理功能
- **创建学生**: POST /api/students - 创建新的学生记录
- **查询单个学生**: GET /api/students/{id} - 根据ID查询学生信息
- **查询学生列表**: GET /api/students - 获取所有学生列表

##### 2. 数据验证
- 必填字段验证（姓名、邮箱、年龄）
- 请求体格式验证
- 详细的验证错误信息返回

##### 3. 错误处理
- 统一的 JSON 错误响应格式
- 详细的错误分类（验证错误、数据库错误、服务器错误）
- 适当的 HTTP 状态码返回

##### 4. 配置管理
- 支持 YAML 配置文件
- 环境变量覆盖配置
- 命令行参数指定配置文件路径
- 配置验证和默认值设置

##### 5. 数据库操作
- 自动创建数据库表结构
- 预编译 SQL 语句防止 SQL 注入
- 连接池管理和资源释放
- 事务支持和错误处理

#### 安装教程

##### 1. 环境要求
- Go 1.21 或更高版本
- Git

##### 2. 克隆项目
```bash
git clone <repository-url>
cd student-api
```

##### 3. 安装依赖
```bash
go mod tidy
```

##### 4. 配置设置
项目支持多种配置方式：

**方式一：使用默认配置文件**
```bash
# 默认使用 config/local.yaml
cp config/local.yaml config/development.yaml
# 编辑配置文件
```

**方式二：使用环境变量**
```bash
export CONFIG_PATH="config/development.yaml"
```

**方式三：命令行参数**
```bash
go run cmd/students-api/main.go --config=config/development.yaml
```

#### 配置文件说明
```yaml
# config/local.yaml
env: "dev"                    # 运行环境 (dev/prod)
storage_path: "storage/storage.db"  # SQLite 数据库文件路径
http_server:
  addr: "localhost:8080"      # HTTP 服务器监听地址
```

#### 使用说明

##### 1. 启动服务
```bash
# 开发环境启动
go run cmd/students-api/main.go

# 生产环境启动
go build -o student-api cmd/students-api/main.go
./student-api --config=config/production.yaml
```

##### 2. API 接口文档

**创建学生**
- **URL**: POST /api/students
- **请求体**:
```json
{
  "name": "张三",
  "email": "zhangsan@example.com",
  "age": 20
}
```
- **响应**:
```json
{
  "id": 1
}
```

**查询学生**
- **URL**: GET /api/students/{id}
- **响应**:
```json
{
  "id": 1,
  "name": "张三",
  "email": "zhangsan@example.com",
  "age": 20
}
```

**查询学生列表**
- **URL**: GET /api/students
- **响应**:
```json
[
  {
    "id": 1,
    "name": "张三",
    "email": "zhangsan@example.com",
    "age": 20
  },
  {
    "id": 2,
    "name": "李四",
    "email": "lisi@example.com",
    "age": 22
  }
]
```

##### 3. 错误响应格式
```json
{
  "status": "Error",
  "error": "错误描述信息"
}
```

#### 项目结构详解
```
student-api/
├── cmd/                           # 应用程序入口
│   └── students-api/
│       └── main.go               # 主程序入口，服务器启动和配置
├── config/                        # 配置文件目录
│   └── local.yaml                # 本地开发环境配置
├── internal/                      # 内部包（不对外暴露）
│   ├── config/                   # 配置管理
│   │   └── config.go             # 配置加载和验证
│   ├── http/handlers/            # HTTP 请求处理器
│   │   └── student/              # 学生相关处理器
│   │       └── student.go        # 学生 CRUD 操作处理器
│   ├── storage/                  # 存储层接口定义
│   │   └── storage.go            # 存储接口定义
│   ├── storage/sqlite/           # SQLite 存储实现
│   │   └── sqlite.go             # SQLite 数据库操作
│   ├── types/                    # 数据模型
│   │   └── types.go              # 学生数据结构定义
│   └── utils/response/           # 响应工具
│       └── response.go            # JSON 响应格式化
├── storage/                       # 数据库文件存储目录
│   └── storage.db                # SQLite 数据库文件
├── go.mod                        # Go 模块定义
├── go.sum                        # 依赖校验文件
└── README.md                     # 项目说明文档
```

#### 开发指南

##### 代码规范
- 使用 Go 标准命名规范
- 函数和结构体添加详细注释
- 错误处理使用明确的错误信息
- 遵循单一职责原则

##### 扩展开发
1. **添加新的 API 端点**: 在 `internal/http/handlers` 下创建新的处理器
2. **添加新的数据模型**: 在 `internal/types` 中定义新的结构体
3. **数据库操作扩展**: 在 `internal/storage/sqlite` 中添加新的方法

#### 部署说明

##### 开发环境
```bash
go run cmd/students-api/main.go
```

##### 生产环境
1. 编译二进制文件
```bash
go build -o student-api cmd/students-api/main.go
```

2. 使用 systemd 服务管理
```ini
# /etc/systemd/system/student-api.service
[Unit]
Description=Student API Service
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/student-api
ExecStart=/opt/student-api/student-api --config=config/production.yaml
Restart=always

[Install]
WantedBy=multi-user.target
```

#### 性能优化建议
- 使用连接池优化数据库连接
- 添加缓存层减少数据库查询
- 使用 gzip 压缩响应数据
- 配置适当的超时设置

#### 故障排除

##### 常见问题
1. **数据库连接失败**: 检查数据库文件路径权限
2. **端口被占用**: 修改配置文件中的监听端口
3. **配置加载失败**: 检查配置文件路径和环境变量

##### 日志查看
项目使用结构化日志，日志包含以下信息：
- 服务器启动和关闭信息
- 数据库操作日志
- HTTP 请求处理日志
- 错误和异常信息

#### 参与贡献
我们欢迎任何形式的贡献！请遵循以下流程：

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

#### 许可证
本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

#### 联系方式
如有问题或建议，请通过以下方式联系：
- 提交 Issue
- 发送邮件到项目维护者

---

**注意**: 本项目仍在积极开发中，API 接口可能会有变动，请关注更新日志。