18 Star 118 Fork 38

嗝嗝 / TP5.1 Restful Api

加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
贡献代码
同步代码
取消
提示: 由于 Git 不支持空文件夾,创建文件夹后会生成空的 .keep 文件
Loading...
README
Apache-2.0

TP5.1 Restful Api

PHP Version License star fork

介绍

PHP7.2 + TP5.1 + Restful Api ,构建的API项目架构,支持API文档输出、API接口自检、开启API JWT模式、反射路由模式、API参数自检等功能

为了本项目拥有更加直白与客观的简易性、阅读性、实用性,所用的扩展和第三方代码,均未考虑高度抽象和深度封装,各位大大可以很简单的看懂源码和框架设计。

如果有需要或涉及到高并发的服务架构,可以在issues提出,或者留言也行,我将参考大家的意愿,出一个版本或demo。

软件架构

软件架构说明

www  WEB部署目录(或者子目录)
├─application           应用目录
│  ├─api        接口模块目录(可以更改,但不建议:很麻烦,模块里面不建议写模型和视图)
│  │  ├─common.php      模块函数文件(接口函数推荐写在这里)
│  │  ├─controller      控制器目录
│  │  │  ├─v1          接口版本模块
│  │  │  ├─v...          接口版本模块
│  ├─common             公共模块目录(可以更改)
│  │
│  ├─command.php        命令行定义文件
│  ├─common.php         公共函数文件
│  └─provider.php       应用容器绑定定义
│  └─tags.php           应用行为扩展定义文件

├─config                应用配置目录
│  ├─api               模块配置目录
│  │  ├─app.php       应用配置
│  │
│  ├─api.php            接口配置
│  ├─app.php            应用配置
│  ├─cache.php          缓存配置
│  ├─cookie.php         Cookie配置
│  ├─database.php       数据库配置
│  ├─log.php            日志配置
│  ├─session.php        Session配置
│  ├─template.php       模板引擎配置
│  └─trace.php          Trace配置

├─route                 路由定义目录
│  ├─route.php          路由定义
│  └─...                更多

├─public                WEB目录(对外访问目录)
│  ├─index.php          入口文件
│  ├─router.php         快速测试文件
│  └─.htaccess          用于apache的重写

├─thinkphp              框架系统目录
│  ├─lang               语言文件目录
│  ├─library            框架类库目录
│  │  ├─think           Think类库包目录
│  │  └─traits          系统Trait目录
│  │
│  ├─tpl                系统模板目录
│  ├─base.php           基础定义文件
│  ├─console.php        控制台入口文件
│  ├─convention.php     框架惯例配置文件
│  ├─helper.php         助手函数文件
│  ├─phpunit.xml        phpunit配置文件
│  └─start.php          框架入口文件

├─extend                扩展类库目录
├─runtime               应用的运行时目录(可写,可定制)
├─vendor                第三方类库目录(Composer依赖库)
├─build.php             自动生成定义文件(参考)
├─composer.json         composer 定义文件
├─LICENSE.txt           授权说明文件
├─README.md             README 文件
├─think                 命令行入口文件

安装教程

  1. 克隆本项目代码
git clone https://gitee.com/china_wangyu/TP5.1-Restful-Api.git
  1. 进入项目工程
cd TP5.1-Restful-Api
  1. 使用composer更新项目扩展,提升项目安全性、可用性

推荐使用composer中国镜像源,具体操作见【文档

composer install

使用说明

必须配置以下内容

  1. 配置api.phpapp.php

api.php 目录在 {项目}/config/api.php

app.php 目录在 {项目}/config/api/app.php

  1. 配置route.php

route.php 目录在 {项目}/route/api.php

如果不修改模块,请直接使用默认配置

开启JWT模式 (可选)

  1. 配置api.php

    // 是否开启授权验证
    'API_AUTHORIZATION' => true,
  2. 修改Base.php项目基类(不建议修改)

    <?php
    /**
     * Created by User: wene<china_wangyu@aliyun.com> Date: 2019/4/3 Time: 16:36
     */
    
    namespace app\api\controller\v1;
    
    use think\restful\jwt\Jwt;
    
    /**
     * Class Reflex API基类
     * @package app\api\controller\v1
     */
    class Base extends \think\restful\Api
    {
        /**
         * Base constructor. 有什么事要在父类执行之后执行的代码,请写在parent::__construct($debug);下
         * @param bool $debug
         */
        public function __construct($debug = false)
        {
            parent::__construct($debug);
        }
    
        /**
         * 继承父类方法,如果有什么要在最开始执行的,请写在里面
         */
        protected function handle()
        {
            if ($this->config['API_AUTHORIZATION']){
                // 开启JWT验证,执行业务代码
                if(!isset($this->param['jwt']) or !isset($this->param['signature'])) {
                    // 没有jwt参数 或 signature 签名
                    $this->error('400 缺少API授权信息~');
                }
                $jwtArr = Jwt::decode($this->param['jwt'],$this->config['API_AUTHORIZATION_KEY']);
                $userJwtSignature = md5(join(',',$jwtArr['data']));
                if ($userJwtSignature !== $this->param['signature']) {
                    $this->error('400 API授权信息错误~');
                }
            }
        }
    }
  3. 修改token.php(不建议修改)

    <?php
    /**
     * Created by User: wene<china_wangyu@aliyun.com> Date: 2019/4/3 Time: 17:34
     */
    
    namespace app\api\controller;
    
    use think\Request;
    use think\restful\Base;
    use think\restful\jwt\Jwt;
    use think\restful\response\Json;
    class Token extends Base
    {
        public function __construct()
        {
            parent::__construct();
        }
    
        public function create()
        {
            $param = $this->param;
            if(empty($param['userName']) or empty($param['userLoginKey'])){
               return Json::json(404,'参数userName/userLoginKey不能为空~');
            }
            $token = $tokenTemplate = $this->config['API_AUTHORIZATION_TOKEN'];
            $token['iat'] = time();
            $token['nbf'] = $token['iat']  + 10;
            $token['exp'] = $token['iat'] + 600;
            $token['data'] = ['userName'=>$param['userName'],
                'userLoginKey'=>$param['userLoginKey']];
            $jwt = Jwt::encode($token,$this->config['API_AUTHORIZATION_KEY']);
            return Json::json(200,'操作成功~',[
                'jwt'=>$jwt,
                'tt'=>  $token['iat'],
                'exp' => $token['exp'],
                'signature' => md5(join(',',$token['data']))
            ]);
        }
    
        /**
         * 刷新时长
         * @return array
         */
        public function reset(){
            $param = $this->param;
            if(empty($param['jwt']))return Json::json(404,'参数jwt不能为空~');
            $jwtArr = Jwt::reset($jwt,$this->config['API_AUTHORIZATION_KEY']);
            return Json::json(200,'操作成功~',[
                'jwt'=> $jwtArr['jwt'],
                'tt'=>  $jwtArr['jwt']['iat'],
                'exp' => $jwtArr['jwt']['exp'],
                'signature' => md5(join(',',$jwtArr['token']['data']))
            ]);
        }
    }
    

API接口编码模板

  • auth文件举例

    代码模板

    <?php
    
    namespace app\api\controller\v1;
    
    /**
     * Class Auth Auth授权类
     * @package app\api\controller\v1
     */
    class Auth extends Base
    {
    
        /**
        * @doc 获取服务器授权1
        * @route /api/v1/auth get
        * @param string $appSecret 授权字符 require|alphaNum 1
        * @param string $appSec2t 授权字符1 require|alphaNum 1
        * @param string $appId 开发者ID
        * @success {"code":400,"msg":"appSecret不能为空","data":[]}
        * @error {"code":400,"msg":"appSecret不能为空","data":[]}
        */
        public function read()
        {
            return $this->success('成功~');
        }
    }

    接口类注释说明

    /**
     * Class Auth Auth授权类
     * @package app\api\controller\v1
     */
    class Auth extends Base

    接口方法注释

    /**
     * @doc 获取服务器授权1
     * @route /api/v1/auth get
     * @param string $appSecret 授权字符 require|alphaNum 1
     * @param string $appSec2t 授权字符1 require|alphaNum 1
     * @param string $appId 开发者ID
     * @success {"code":400,"msg":"appSecret不能为空","data":[]}
     * @error {"code":400,"msg":"appSecret不能为空","data":[]}
     */
    public function read()
    {
        return $this->success('成功~');
    }

    接口方法注释参数说明

    @ 名称 参数1注解 参数2注解 参数3注解
    doc API接口文档
    route API路由规则 请求类型
    param api参数 验证规则 默认值
    success API请求成功返回json示例
    error API请求失败返回json示例

接受接口请求数据

  • url 请求样例
http://127.0.0.1:8000/api/v1/auth?appSecret=12&appSec2t=12
  • 代码样例
public function read()
{
    # $this->param 就是接口请求数据,包含请求版本号,请求接口类名称
    return $this->success('成功~',$this->param);
}
  • 返回样例
{
"responseCode": 200,
"responseMsg": "成功~",
"responseData": {
    "appSecret": "12",
    "appSec2t": "12",
    "version": "v1",
    "controller": "auth"
    }
}

返回json数据

注意本函数与 TP 内置 think\Controllersuccess\errror同名

  • 状态为200的 样例

    public function read()
    {
        return $this->success('成功~');
    }
    {
    "responseCode": 200,
    "responseMsg": "成功~",
    "responseData": {
        "appSecret": "12",
        "appSec2t": "12",
        "version": "v1",
        "controller": "auth"
        }
    }
  • 状态为400的 样例

    public function read()
    {
        return $this->error('成功~');
    }
    {
    "responseCode": 400,
    "responseMsg": "参数错误:appSecret不能为空",
    "responseData": []
    }
  • success/error函数参数说明

    参数名称 注解 类型 默认值
    msg 接口调用提示
    data 返回数据 请求类型

输出API文档

  1. 需要设置api.phpAPI_AUTHORIZATION值为false

    // 是否开启授权验证
    'API_AUTHORIZATION' => false,
  2. 打开cmd/ssh工具

  3. 进入项目目录

  4. 执行命令

    C:\Users\zhns_\Desktop\php\TP5.1-Restful-Api [master ≡ +2 ~223 -1 !]
    >  php think api:make
    API markdown 接口文档地址: C:\Users\zhns_\Desktop\php\TP5.1-Restful-Api\\API接口文档2019-04-16 15.md
自检API接口
  1. 需要设置api.phpAPI_AUTHORIZATION值为false

    // 是否开启授权验证
    'API_AUTHORIZATION' => false,
  2. 打开cmd/ssh工具

  3. 进入项目目录

  4. 开启接口服务

    • 使用PHP内置服务器
    php -S {IP地址}:{端口} -t {项目目录}/public/
    • TP5 启动服务
    > php think run -H {IP地址} -P {端口}
    
    ThinkPHP Development server is started On <http://127.0.0.1:8000/>
    You can exit with `CTRL-C`
    Document root is: E:\VirtualBox\vms\CICD\labs\tp5restfulapi_architecture\public
  5. 然后配置项目 api.php 配置文件的参数 (可选)

'API_HOST'=> 'http://127.0.0.1:8000',# 设置API网址

如果没有配置这个,请在执行的时候加上-H指定网址

  1. 输入自检命令 php think API -C 1

    • 基本命令
    C:\Users\zhns_\Desktop\php\TP5.1-Restful-Api [master ≡ +2 ~223 -1 !]
    >  php think api:check
    API markdown 自检文档地址: C:\Users\zhns_\Desktop\php\TP5.1-Restful-Api\\API自检文档2019-04-16 15.md
    • 指定网址 php think API -C 1 -H
    C:\Users\zhns_\Desktop\php\TP5.1-Restful-Api [master ≡ +2 ~223 -1 !]
    >  php think api:check -H http://127.0.0.1:8000
    API markdown 自检文档地址: C:\Users\zhns_\Desktop\php\TP5.1-Restful-Api\\API自检文档2019-04-16 16.md

接口文档样例

详情请点击 【接口示例文档.md】查看效果。

本来想写成json格式的,后面想想还是这个makdown文档最为方便,希望大家喜欢。

项目自评

本扩展或者说是一个TP5.1+PHP7.2的后端项目API架构, 主要是帮助刚刚入行或者快速建站的朋友们,进行项目快速迭代开发, 把接口授权、接口验证、参数校验、接口文档输出、接口自验包裹封装起来, 只为大家用的安心。

帮助作者

项目开发或者扩展开发,都需要不断地编码尝试与线上环境验证。 所需的资源和时间都是有成本的,如果项目帮助到您了, 如果您有心帮助作者,请点击下方的捐赠按钮

参与贡献

  1. Fork 本仓库
  2. 新建 ts_{用户名} 分支
  3. 提交代码
  4. 新建 Pull Request

联系作者

Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

简介

TP5.1-Restful-Api 有全新版本了,更名为:TRR (ThinkPHP51 Reflection Restful API简写),更为简单、优雅、易上手,详情请点击后方链接: 展开 收起
PHP 等 3 种语言
Apache-2.0
取消

发行版

暂无发行版

贡献者

全部

近期动态

加载更多
不能加载更多了
PHP
1
https://gitee.com/china_wangyu/TP5.1-Restful-Api.git
git@gitee.com:china_wangyu/TP5.1-Restful-Api.git
china_wangyu
TP5.1-Restful-Api
TP5.1 Restful Api
master

搜索帮助

14c37bed 8189591 565d56ea 8189591