Need help with lumen-api-demo?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

liyu001989
859 Stars 219 Forks MIT License 282 Commits 5 Opened issues

Description

Lumen rest api demo with Dingo/Api, JWT, CORS, PHPUNIT

Services available

!
?

Need anything else?

Contributors list

# 41,588
PHP
Laravel
lumen-f...
lumen
248 commits
# 34,679
Go
mesos
Apache ...
Docker
2 commits
# 8,460
lumen-f...
lumen
C++
Node.js
1 commit
# 430,189
lumen-f...
PHP
HTML
Laravel
1 commit

lumen-api-demo

这是一个比较完整用 lumen 5.7 写的的 REST API 例子。使用了

dingo/api
,jwt 实现登录,功能上很简单,登录,注册,发帖,评论,单元测试(正在补充)。

StyleCI License donate donate

lumen5.x 请看对应的分支

有需要随时联系我

  • lumen/laravel/restful 交流群: 216721539 (备注 laravel 或 lumen)
  • email: [email protected]

ENGLISH README

教程

Laravel 教程 - 实战构架 API 服务器

USEFUL LINK

读文档很重要,请先仔细读读文档 laravel, dingo/api,jwt,fractal 的文档。

USAGE

$ git clone [email protected]:liyu001989/lumen-api-demo.git
$ composer install
$ 设置 `storage` 目录必须让服务器有写入权限。
$ cp .env.example .env
$ vim .env
    DB_*
        填写数据库相关配置 your database configuration
    JWT_SECRET
        php artisan jwt:secret
    APP_KEY
        lumen 取消了key:generate 所以随便找个地方生成一下吧
        md5(uniqid()),str_random(32) 之类的,或者用jwt:secret生成两个copy一下

$ php artisan migrate $ php artisan db:seed (默认添加了10个用户,50篇帖子, 100条评论)

头信息中可以增加 Accept:application/vnd.lumen.v1+json 切换v1和v2版本

api文档在public/apidoc里面有一份,网络不好的可以直接查看本地的文档, 也可以看上面的 项目api在线文档

我是这样生成的: apidoc -i App/Http/Controllers/Api/V1/ -o public/apidoc/

如果访问一直不对,可以进入public 目录执行

php -S localhost:8000 -t public
,然后尝试调用几个接口,从而确定是否为web服务器的配置问题。

REST API DESIGN

大概举个例子说明一下 rest api 吧

github 的 api 真的很有参考价值 github-rest-api

    例子: 用户,帖子,评论
    get    /api/posts                帖子列表
    post   /api/posts                创建帖子
    get    /api/posts/5              id为5的帖子详情
    put    /api/posts/5              替换帖子5的全部信息
    patch  /api/posts/5              修改部分帖子5的信息
    delete /api/posts/5              删除帖子5
    get    /api/posts/5/comments     帖子5的评论列表
    post   /api/posts/5/comments     添加评论
    get    /api/posts/5/comments/8   id为5的帖子的id为8的评论详情
    put    /api/posts/5/comments/8   替换帖子评论内容
    patch  /api/posts/5/comments/8   部分更新帖子评论
    delete /api/posts/5/comments/8   删除某个评论
    get    /api/users/4/posts        id为4的用户的帖子列表
    get    /api/user/posts           当前用户的帖子列表

// 登录,刷新,登出
// 或许可以有更好的命名
post    /api/authorizations  创建一个token
put     /api/authorizations/current  刷新当前 token
delete  /api/authorizations/current  删除当前 token

问题总结

Lumne 和 Laravel 选哪个

首先建议大家使用 Laravel,参考超哥的答案 https://laravel-china.org/articles/5079/laravel-or-lumen。Laravel 提供了更全的功能,更容易使用,非常方便。Lumen 只是为了Api 而生,而我们通常的业务场景会是一套 Api 和一套后台管理系统,使用 Laravel 会让你更快更好的完成需求。非常非常不建议新手直接使用 Lumen。

jwt 使用

lumen 5.2 取消了session,没有了 auth 的实例,所以使用jwt的时候需要配置一下,注意 config/auth.php 中的配置,而且 user 的 model 需要实现 Tymon\JWTAuth\Contracts\JWTSubject;

基本用法, jwt 会 encode 对应模型的 id,生成token,客户端拿到 token,放在 Authorization header 中

Authorization: Bearer token

验证的逻辑就是 decode token 拿到id,然后找到对应的用户。当然了,你可能需要 encode 额外的字段,那么可以使用 CustomClaims。

token 有两个时间,一个是过期时间(ttl),一个是可刷新时间(refresh_ttl)。怎么理解,比如 ttl 是 1 天,refresh_ttl 是1周,那么 token 一天后过期,但是1周之内你仍然可以用这个 token 换取一个新的 token,而这个新 token 又会在 1 天后过期,1周内可刷新。

举个例子,用户登录了你的应用,并且每天都会打开你的应用,你的应用如果发现这个 token 过期了,会主动刷新一次,如果成功那么用户依然是登录的。当用户1周都没有登录过你的应用,那么他就需要重新登录了。

客户端的逻辑应该是,首先判断这个 token 是否过期了,1是通过两个 ttl 判断,因为客户端是知道这两个时间的,2是调用需要授权的接口返回的状态码(401),判断过期了则主动尝试刷新,刷新成功了,重置token和时间,失败了,则跳转到登录页面。

使用mail

写了个例子,注册之后给用户发送邮件, 可以参考一下。

  • composer 加 illuminate/mail 和 guzzlehttp/guzzle 这两个库
  • 在 bootstrap/app.php 或者 provider 中注册 mail 服务
  • 增加配置 mail 和 services, 从 laravel 项目里面 cp 过来
  • 在 env 中增加 MAIL_DRIVER,账户,密码等配置
transformer 的正确使用

transformer 是个数据转换层,帮助你格式化资源。还可以帮助你处理资源之间的引用关系。

试着体会一下以下几个url的也许就明白了

是不是很强大,我们只需要提供资源,及资源之间的引用关系,省了多少事

transformer 如何自定义格式化资源

dingo/api 使用了 Fractal 做数据转换,fractal 提供了3种基础的序列化格式,Array,DataArray,JsonApi,在这里有详细的说明 http://fractal.thephpleague.com/serializers/。DataArray 是默认的,也就是所有资源一定有data和meta。当然也可以按下面这样自定义:

    只需要在 bootstrap/app.php 中设置 serializer 就行了。具体见 bootstrap/app.php 有注释
    $app['Dingo\Api\Transformer\Factory']->setAdapter(function ($app) {
        $fractal = new League\Fractal\Manager;
        // 自定义的和fractal提供的
        // $serializer = new League\Fractal\Serializer\JsonApiSerializer();
        $serializer = new League\Fractal\Serializer\ArraySerializer();
        // $serializer = new App\Serializers\NoDataArraySerializer();
        $fractal->setSerializer($serializer);,
        return new Dingo\Api\Transformer\Adapter\Fractal($fractal);
    });

个人认为默认的 DataArray 就很好用了,基本满足了 API 的需求

422 错误提示

参考了 github 的错误提示,这样可能更方便 app 对接,格式固定有field 和code,field为字段名,code为错误提示。

如果想用默认的,在 BaseController 中使用下面的代码即可 throw new ValidationHttpException($validator->errors());

TODO

  • [ ] 单元测试

License

MIT license

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.