运行环境要求 PHP7.2+, 建议 PHP7.4.33, 兼容 PHP8.0+
JSONAPI 是一个根据数据库表全自动生成接口和文档的系统,
欢迎大家在自己项目中使用它做二次开发.
不从零开始写数据库操作相关功能,
尽可能防止 SQL 注入等漏洞出现,
尽量使用经过多数人验证的各种方法,
所以 JSONAPI 基于ThinkPHP v6.1.0开发,
严格来说更像是对ThinkPHP开发使用上的部份心得汇总,
更多开发技巧可参考ThinkPHP官方文档.
- 无需建路由对应的控制器 (Thinkphp 原本是需要的)
- 无需建数据表对应的模型 (Thinkphp 原本是需要的)
- 自动根据数据表生成标准的 JSON 接口,包含增删改查
- 自动生成美观的接口文档,包括自己写的其他所有接口
- 数据可验证,所有接口自动加载自定义的规则
- 所有接口请求都有事件产生,可自行订阅
- 可自由新建控制器,会自动继承增删改查方法也可重写
- 可自由写新的功能更强大的接口,函数注释会自动生成文档
- 动态生成数据模型,无需直接用数据库方法
- 可对数据进行严格且灵活的权限控制,增删改查独立控制
- 可自由添加中间件,服务,容器和注入等
- 其他 ThinkPHP 的优点统统继承,事件驱动,分布式数据库,Swoole 以及协程等等
# git clone https://github.com/d86e/jsonapi
# cd jsonapi
# composer install
在 /config/database.php 或 .env 配置好数据库连接登录信息
开发环境请执行如下命令启动 web 服务,默认端口为8000
# php think run
或者自定义端口
# php think run -p 8080
如果是生产环境,请将 web 根目录设为 /public 并将入口文件设为 index.php
同时给站点设置好隐藏 index.php 的伪静态规则
Apache 示例:
<IfModule mod_rewrite.c>
Options +FollowSymlinks -Multiviews
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ index.php/$1 [QSA,PT,L]
</IfModule>
Nginx 示例:
location / {
if (!-e $request_filename){
rewrite ^(.*)$ /index.php?s=$1 last; break;
}
}
如果需要更新 ThinkPHP 框架版本请使用以下命令
# composer update topthink/framework
请通过 web 链接访问安装权限控制数据库表
http://localhost:8000/install
至此所有安装操作完成, 可以访问自动生成的接口文档了
http://localhost:8000/api
文档访问地址是api这个控制器的默认方法,所以应该是类似这样的地址
http://localhost:8000/api
每次访问程序会读一遍数据库和控制器目录动态显示这个文档,
而不是生成静态的文档文件,以确保文档随时处于最新状态.
此文档仅在app_debug模式开启的情况下显示,
在生产环境关闭 app_debug 模式后访问会是一个空白页面,以此确保线上系统的文档安全.
默认情况下,程序会读取表名做为控制器名(不包括表前缀),
然后再在控制器名后加上增删改查其中之一种方法,
得到一个完整的接口地址(每个接口需要添加api路由标识).
示例(读取用户列表):http://localhost:8000/api/User/list
程序还会读取 SQL 表的的注释做为接口的说明名称,
同时读取每个 SQL 表的字段信息做为接口参数说明,
包括 字段名, 字段类型, 默认值, 字段注释
如果需要自己写控制器和一些高级方法,
同样可以自动生成接口及文档
但是请写好函数的注释,
程序会读取@name 后面的函数说明名称,
会读取@param 后面的字段名和注释,
字段名和注释中间用空格隔开,注释后面是必填,再后面是默认值,
示例 @param name 产品的名字 否 Null
基础控制器内已经写了增删改查方法及事件触发,
自动生成的接口或自定义控制器继承它都会触发接口访问事件,
事件标识是RequestApi
可自行写监听类或订阅类,
监听类的目录是/app/listener/
订阅类的目录是/app/subscribe/
事件RequestApi会把整个 Request Param 做为参数传递给监听或订阅类,
监听和订阅类需要在事件定义文件app/event.php内注册绑定才会生效,
代码内有写了一个RequestApi的监听和订阅以及注册示例.
也可以在任意地方直接使用Event::listen对事件进行监听,
或者使用Event::subscribe对事件进行订阅,
更多高级用法和说明请看 ThinkPHP 文档 - 事件
所有接口支持自定议数据验证,会动自加载验证规则类.
验证规则类在/app/validate内, 里面有一个示例User.php
支持场景验证, 验证错信息支持多语言.
更多使用方法请看 ThinkPHP - 验证器
提交的参数里,这些是可以用的:
field过滤返回想要的字段,
page 字段是提交分页信息的,用法遵循 Thinkphp,
order 数据排序.
接口支持所有类型的请求,get、post 等等
整个权限控制一共使用了四张数据表,如有和你业务系统表重名请自行修改,
auth表用来记录其他表的名称和增删改查四种分别开启权限的模式,
一共有三种模式:
0、是只能操作用户自有数据.
1、规则表没有规则时可操作所有数据.
2、规则表没有规则时不可操作任何数据.
增删改查分别对应的规则表:
auth_write_rule
auth_delete_rule
auth_update_rule
auth_read_rule
每个规则表都会记录 name表名 data_id数据 id user_id用户 id type是否可写.
程序会先读取auth表以确认访问的数据表是否开启了权限控制以及控制的模式.
然后会拿用户 id 去各个操作方法对应的表里找规则以决定用户是否有相关的操作权限.
一般约定用户 id 用user_id, 而数据 id 用data_id,
在baseModel.php内使用了Session::get('user_id')的方式读取用户 id,
所以在其他地方处理用户登录时,应该把用户 id 以user_id为索引存入 Session 内.
如果你不想使用 Session 记录用户的 id, 请自行改用别的方式存取, 仅在baseModel.php内有两个地方使用Session::get('user_id')
测试工具用的是 PHPUnit 9.6.17
文档地址 https://docs.phpunit.de/en/9.6/index.html
封装了一个 Trait 类TestExtendTrait, 用于向控制器的方法请求数据,
可以在测试类中直接使用, 像这样:
use tests\TestTesxt
tests/ApiTest.php 是接口的单元测试类,
里面已经写好了增删改查和文档页面的测试,
共六个测试方法六个断言,
测试user表, 请自行增加此表和测试数据,
修改 tests/ApiTest.php 内的测试字段和数据.
然后执行单元测试命令:
./vendor/bin/phpunit tests/ApiTest.php
当测试通过后, 程序会输出:
...... 6 / 6 (100%)
Time: 00:00.095, Memory: 10.00 MB
OK (6 tests, 6 assertions)
想参与开发 jsonapi, 应该怎么做?
首先 Fork 一份代码仓库, 然后git clone你的仓库到本地,
按照上面的安装流程把工程跑起来,
实现 jsonapi 功能的核心文件一共有三个:
/app/BaseController.php,
Api.php 是直接继承它获得增删改查方法的,
自己如果确实需要建其他控制器建议也继承它以便继承增删改查方法.
/app/model/BaseModel.php,
所有的匿名模型都是继承它实现权限控制和数据操作的,
自己如果确实需要建模型建议也继承它以便继承权限和数据操作.
/app/controller/Api.php
此控制器的默认方法实现了接口文档的生成和输出,
直接输出 HTML,仅在app_debug 模式下有输出.
JSONAPI 的实现整体代码量极其的少,
每个函数都有非常详细的注释.
开发新的功能或修改之后commit并git push到你的仓库中,
再通过Pull Request到本仓库, 审核通过后会第一时间合并到主分支.
同时也欢迎直接在 Github 加入到 JSONAPI 的开发团队中,请和Tommy Tan ([email protected])取得联系.
提前感谢每一位参与者.
请参阅 ThinkPHP 完全开发手册 ThinkPHP 核心框架包.
如果 JSONAPI 对你有帮助, 请给项目打赏支持.
JSONAPI 遵循 Apache2 开源协议发布，并提供个人和商业免费使用。 所使用的底层框架 ThinkPHP 版权归 ThinkPHP 官方所有, 本项目可能包含的第三方源码和二进制文件之版权信息另行标注。
版权所有 Copyright 2024 by Tommy Tan All rights reserved。
更多细节参阅 LICENSE.txt