# hy-webman-api

**Repository Path**: huanyi/hy-webman-api

## Basic Information

- **Project Name**: hy-webman-api
- **Description**: 🎈 hy-webman：专注于Web开发的高效框架，提供简洁API和强大功能，支持快速构建现代Web应用。
- **Primary Language**: PHP
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# hy-webman-api

## 项目简介

hy-webman-api 基于 [webman](https://www.workerman.net/webman) 高性能 PHP 框架，集成了 APIJSON 协议的高兼容后端，支持自动生成 Service/Model、分层架构、定时任务自动注册、灵活请求验证、批量测试等。适合中大型项目和团队协作，兼容 APIJSON 官方协议，极大提升开发效率和接口自由度。

## 主要功能亮点

- **APIJSON 协议高兼容**：支持对象/数组/多表/聚合/分组/排序/with 关联/路径赋值/逻辑/模糊/正则/JSON 查询等，兼容官方所有主流特性。
- **自动生成 Service/Model**：一键生成业务 Service 层和 Eloquent 模型，极简维护。
- **分层架构**：Logic/Service/Controller/Model 分层，业务逻辑清晰，易于团队协作。
- **定时任务自动注册**：crontab 目录下任务类自动注册，无需手动维护。
- **灵活请求验证**：支持动态指定验证类和 action，兼容 GET/POST/JSON 多种参数来源。
- **批量自动化测试**：自带 PHP 脚本一键批量测试所有 APIJSON 主要特性。
- **高性能/易扩展**：基于 webman，支持高并发、热更新、灵活扩展。
- **SQL 日志与调试**：支持 SQL 日志输出，便于开发调试。

## 主要目录结构

```
webman/
  app/
    api/controller/    # 控制器层
    logic/             # 业务逻辑层（只需维护这里）
    service/           # 自动生成的 Service 层
    model/             # Eloquent 模型（支持自动生成）
    crontab/           # 定时任务类（每个任务一个文件，自动注册）
    process/           # 进程类（如 Task.php 自动注册定时任务）
    ...
  config/              # 配置文件
  public/              # 入口目录
  scripts/             # 代码生成脚本
  routes/              # 路由
  ...
```

## APIJSON 协议支持亮点

- 多模型/多表查询（根级直接传模型名或 [] 结构）
- 字段筛选与别名（@column、id:name）
- 聚合函数（max、min、sum、count 等，支持别名）
- 逻辑运算符（id{}、id!{}、id&{}、id|{}）
- 模糊/正则/JSON 包含查询（content$、content~、field<>）
- 分页与统计（page、count、query=1/2）
- 路径赋值与重命名（total@、num@、info@）
- 关联加载（@with: ["user:id,name"]）
- 排序/分组（@order、@group）
- 完全兼容 APIJSON 官方协议
- 详见 [APIJSON.md](APIJSON.md)

## APIJSON 增删改查用法

### 控制器说明

`app/apijson/controller/ReqController.php` 提供了标准的增删改查接口：
- GET  `/apijson/gets`    → 查询
- POST `/apijson/posts`   → 新增
- PATCH `/apijson/patchs` → 更新
- DELETE `/apijson/deletes` → 删除

每个方法会自动分发到对应的 Eloquent 操作。

### 请求示例

#### 新增（POST /apijson/posts）
```json
{
  "oldreview": {
    "name": "test",
    "status": 1
  }
}
```

#### 更新（PATCH /apijson/patchs）
```json
{
  "oldreview": {
    "id": 1,
    "name": "new name"
  }
}
```

#### 删除（DELETE /apijson/deletes）
```json
{
  "oldreview": {
    "id": 1
  }
}
```

#### 查询（GET /apijson/gets）
```json
{
  "oldreview": {
    "id": 1
  }
}
```

- 新增/更新会自动过滤掉以 `@` 开头的参数和 type/parent 字段。
- 更新/删除操作必须传递主键 `id`。
- 所有异常会抛出详细的错误信息。

### 安全开关说明

- 新增（POST）、修改（PATCH）、删除（DELETE）操作默认关闭。
- 需在 `config/Apijson.php` 配置文件中将 `allow_post`、`allow_patch`、`allow_delete` 设置为 `true` 才可用。
- 示例：
  ```php
  return [
      'show_sql' => true,
      'allow_post' => true,   // 允许新增
      'allow_patch' => false, // 禁止修改
      'allow_delete' => false // 禁止删除
  ];
  ```
- 未开启时，接口会直接返回错误提示，防止误操作。

### 权限模块说明

- 每次 APIJSON 请求都会自动调用权限校验类（默认 app/apijson/permission/ApiJsonPermission.php）。
- 配置方式：在 `config/Apijson.php` 设置 `permission_checker`，如：
  ```php
  'permission_checker' => \app\apijson\permission\ApiJsonPermission::class,
  ```
- 权限类需实现静态方法 `check($method, $json, $request)`，不通过时可直接抛出异常。
- 示例：
  ```php
  class ApiJsonPermission {
      public static function check($method, $json, $request) {
          // 可扩展权限验证逻辑
          // 不通过可抛出 \app\apijson\core\ApiJsonException
          return true;
      }
  }
  ```
- 你可以根据业务需要扩展 check 方法，实现登录校验、角色校验、字段级权限等。

## 快速上手

1. 安装依赖
    - `composer install`（确保已安装 webman、illuminate/database 等依赖）
2. 配置模型映射
    - 编辑 `webman/app/apijson/config/ModelMap.php`，添加表名与模型类映射。
3. 启动服务
    - `php start.php start`
4. 典型请求与协议详见 [APIJSON.md](APIJSON.md)
5. 批量测试
    - 运行 `php apijson_test.php`，自动批量测试所有主要特性。

## Service/Logic 分层与自动生成
- 只需维护 `app/logic/` 下的业务逻辑类（如 `TestLogic.php`，静态方法）
- 运行 `php scripts/generate_services.php`，自动为每个 logic 生成对应的 service 文件
- 详细说明见 [webman/app/README.md](webman/app/README.md)

## 模型自动生成
- 运行 `php scripts/generate_models_with_base.php`，自动为每个数据表生成 Base 模型和可扩展模型
- 详细说明见 [模型.md](模型.md)

## 定时任务（Crontab）自动注册机制
- 在 `app/crontab/` 目录下，每个定时任务写成一个独立 PHP 类文件
- 每个任务类需定义静态 `$rule`（定时表达式）和 `run()` 方法
- `app/process/Task.php` 会自动扫描并注册所有任务，无需手动维护
- 详细说明见 [crontab/定时任务.md](crontab/定时任务.md)

## 请求验证最佳实践

### 推荐用法：validate_request 封装函数

在 `app/functions.php` 已内置 `validate_request` 动态验证函数，推荐所有控制器统一调用：

```php
// 控制器示例
public function json(Request $request)
{
    $data = $request->get() + $request->post();
    $validated = validate_request(\app\api\request\IndexRequest::class, $data, 'Json');
    // 业务逻辑...
    return json(['code' => 0, 'data' => $validated]);
}
```

- 支持动态指定 Request 验证类和 action 方法
- 兼容 GET/POST/JSON 多种参数来源
- 便于单元测试和复用

### BaseRequest 说明
- 只通过构造函数传入参数，不依赖 webman request 对象
- 支持多 action 验证方法（如 `getRulesByJson`）
- 推荐所有自定义请求验证类继承 BaseRequest

### 旧方案兼容
如需兼容传统 ThinkPHP 验证器写法，可参考 `topthink/think-validate` 官方文档。

## 相关文档
- [APIJSON.md](APIJSON.md)（协议与用法说明，强烈推荐）
- [webman 官方文档](https://www.workerman.net/webman)
- [webman/app/README.md](webman/app/README.md)（分层与自动生成说明）
- [模型.md](模型.md)（模型自动生成说明）
- [请求验证.md](请求验证.md)（请求验证自动生成说明）
- [crontab/定时任务.md](crontab/定时任务.md)（定时任务自动注册说明）

## License
MIT