# api

**Repository Path**: pear2007/api

## Basic Information

- **Project Name**: api
- **Description**: gin + gorm  api 
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GORM Edu API 文档

## 项目介绍

这是一个基于 Go 语言、GORM 和 Gin 框架开发的用户管理系统示例项目。该项目提供了基本的用户 CRUD（创建、读取、更新、删除）操作的 API 接口，可作为学习 Go Web 开发和 GORM ORM 使用的参考。

## 项目结构

```
gorm-edu/
├── comm/
│   ├── crud.go  # 数据库 CRUD 操作函数
│   └── user.go  # User 数据模型定义
├── go.mod       # Go 模块依赖文件
├── go.sum       # 依赖版本锁定文件
├── main.go      # 主程序入口，包含 API 路由定义
└── README.md    # 项目文档（当前文件）
```

## 技术栈

- Go 语言
- GORM (Go 对象关系映射框架)
- Gin (Web 框架)
- MySQL 数据库

## 安装与运行

### 前提条件

- 安装 Go 环境 (推荐 Go 1.16+)
- 安装 MySQL 数据库

### 安装步骤

1. 克隆项目代码

```bash
git clone <项目仓库地址>
cd gorm-edu
```

2. 安装依赖

```bash
go mod tidy
```

3. 配置数据库连接

编辑 `comm/crud.go` 文件中的数据库连接信息：

```go
dsn := "root:123456@tcp(127.0.0.1:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local"
```

修改为您自己的 MySQL 连接信息，包括用户名、密码、主机地址、端口和数据库名。

4. 运行项目

```bash
go run main.go
```

默认情况下，服务将在 `http://localhost:8080` 启动。

## API 接口说明

### 1. 首页接口

#### 请求信息
- **请求方法**: GET
- **请求路径**: `/`
- **请求参数**: 无

#### 响应示例

```json
{
  "message": " 首页"
}
```

### 2. 添加用户接口

#### 请求信息
- **请求方法**: GET
- **请求路径**: `/add`
- **请求参数**: 无

#### 响应示例

成功响应:
```json
{
  "message": "添加用户成功",
  "user": {
    "ID": 1,
    "Name": "张强",
    "Email": null,
    "Age": 25,
    "Birthday": null,
    "MemberNumber": {
      "String": "",
      "Valid": false
    },
    "ActivatedAt": {
      "Time": "0001-01-01T00:00:00Z",
      "Valid": false
    },
    "CreatedAt": "2023-10-20T15:30:45+08:00",
    "UpdatedAt": "2023-10-20T15:30:45+08:00"
  }
}
```

失败响应:
```json
{
  "error": "添加用户失败"
}
```

### 3. 根据 ID 查询用户接口

#### 请求信息
- **请求方法**: GET
- **请求路径**: `/user/:id`
- **URL 参数**: `id` (用户 ID)

#### 响应示例

成功响应:
```json
{
  "message": "查询用户成功",
  "user": {
    "ID": 1,
    "Name": "张强",
    "Email": null,
    "Age": 25,
    "Birthday": null,
    "MemberNumber": {
      "String": "",
      "Valid": false
    },
    "ActivatedAt": {
      "Time": "0001-01-01T00:00:00Z",
      "Valid": false
    },
    "CreatedAt": "2023-10-20T15:30:45+08:00",
    "UpdatedAt": "2023-10-20T15:30:45+08:00"
  }
}
```

无效 ID 响应:
```json
{
  "error": "无效的用户ID"
}
```

查询失败响应:
```json
{
  "error": "查询用户失败"
}
```

### 4. 根据 ID 删除用户接口 (当前主程序中未实现，需自行添加路由)

#### 请求信息
- **请求方法**: DELETE
- **请求路径**: `/user/:id`
- **URL 参数**: `id` (用户 ID)

#### 实现参考代码

```go
router.DELETE("/user/:id", func(c *gin.Context) {
  id := c.Param("id")
  userID, err := strconv.ParseUint(id, 10, 32)
  if err != nil {
    c.JSON(400, gin.H{"error": "无效的用户ID"})
    return
  }
  if err := comm.DeleteUser(uint(userID)); err != nil {
    c.JSON(500, gin.H{"error": "删除用户失败"})
    return
  }
  c.JSON(200, gin.H{"message": "删除用户成功"})
})
```

#### 响应示例

成功响应:
```json
{
  "message": "删除用户成功"
}
```

失败响应:
```json
{
  "error": "删除用户失败"
}
```

## 数据模型

### User 结构体

```go
type User struct {
  ID           uint           // 主键 ID
  Name         string         // 用户名
  Email        *string        // 邮箱 (可为空)
  Age          uint8          // 年龄
  Birthday     *time.Time     // 生日 (可为空)
  MemberNumber sql.NullString // 会员编号 (可为空)
  ActivatedAt  sql.NullTime   // 激活时间 (可为空)
  CreatedAt    time.Time      // 创建时间 (GORM 自动管理)
  UpdatedAt    time.Time      // 更新时间 (GORM 自动管理)
}
```

## 数据库操作函数

项目中提供了以下数据库操作函数：

1. `InitDB()` - 初始化数据库连接并自动迁移表结构
2. `CloseDB()` - 关闭数据库连接
3. `CreateUser(user *User) error` - 创建用户
4. `GetUser(id uint) (User, error)` - 根据 ID 查询用户
5. `DeleteUser(id uint) error` - 根据 ID 删除用户

## 使用示例

### 调用添加用户接口

```bash
curl http://localhost:8080/add
```

### 调用查询用户接口

```bash
curl http://localhost:8080/user/1
```

## 注意事项

1. 当前实现的 `/add` 接口使用 GET 请求添加固定数据的用户，在实际项目中应使用 POST 请求并接收请求体中的用户数据。
2. 错误处理可以进一步完善，提供更详细的错误信息。
3. 数据库连接信息不应硬编码在代码中，建议使用配置文件或环境变量。
4. 生产环境中应添加身份验证和授权机制。

## 扩展和改进建议

1. **添加用户更新接口**：实现一个 PUT 或 PATCH 接口，允许更新用户信息。

2. **添加分页查询接口**：实现一个支持分页、排序和过滤的用户列表查询接口。

3. **添加用户认证**：实现 JWT 或 Session 认证机制，保护 API 接口。

4. **添加日志记录**：集成日志系统，记录 API 请求和错误信息。

5. **添加单元测试和集成测试**：为数据库操作和 API 接口编写测试用例。

6. **添加数据验证**：对输入数据进行验证，确保数据的合法性。

7. **添加 API 版本控制**：在 API 路径中添加版本信息，如 `/v1/user/:id`。

8. **使用配置文件**：将数据库连接信息等配置项移至配置文件中。

## 常见问题

### 1. 如何修改数据库连接信息？

编辑 `comm/crud.go` 文件中的 `InitDB()` 函数，修改 `dsn` 变量的值，将其替换为您自己的数据库连接信息。

### 2. 如何添加新的 API 接口？

1. 在 `comm/crud.go` 中添加相应的数据库操作函数
2. 在 `main.go` 中添加新的路由和处理函数
3. 在 README.md 中更新 API 文档

### 3. 为什么查询不到用户数据？

可能的原因：
- 用户 ID 不存在
- 数据库连接有问题
- 表结构不匹配，尝试重新执行自动迁移

### 4. 如何处理大并发请求？

- 使用连接池管理数据库连接
- 考虑使用缓存减少数据库查询
- 实现限流机制防止过载

## 贡献指南

欢迎提交 Issue 和 Pull Request 来改进这个项目。在提交代码前，请确保您的代码符合项目的代码风格和质量要求。




## Go代理 命令行 输入 一下命令
```
    go env -w GO111MODULE=on
    go env -w GOPROXY=https://goproxy.cn,direct
```

## 安装依赖
```
    go mod tidy
```


###  web 项目 安装依赖
```
    cd web
    npm install

    npm run dev
```