xdapp / service-register
Requires
- php: ^7.0.0
- ext-hprose: *
- ext-mbstring: *
- ext-snappy: *
- ext-swoole: >= 4.0
- hprose/hprose: ~2.0
README
XDApp RPC Service SDK
XDAppRPC服务SDK
依赖
- PHP >= 7.0(推荐7.2)
- PHP Swoole 扩展 >=4.0,推荐最新版本
- PHP hprose 扩展
- PHP mbstring 扩展 (通常默认安装)
- PHP snappy 扩展,安装 see https://github.com/kjdev/php-ext-snappy
安装
首先需要安装composer,安装方式(see https://getcomposer.org/download/)
在已有PHP项目中加入依赖包
composer require xdapp/service-register
在新项目中使用(HelloWorld,适合新手)
1.新建文件夹,创建 composer.json
文件,内容:
{ "minimum-stability": "stable", "autoload": { "psr-4": { "App\\": "src/" } }, "require": { "xdapp/service-register": "^1.1" } }
2.运行 composer install
,稍等片刻即可安装好(若网络慢,可使用中国镜像,see https://pkg.phpcomposer.com/)
3.创建一个文件夹,比如叫 service
,然后创建一个 test.php
文件,内容:
<?php return new class() { function hello() { return "hello world"; } };
4.创建 run.php
文件:
<?php use XDApp\ServiceReg\Service; $service = Service::factory('demo', 'test', '123456'); // app、service、token $service->addServiceByDir(__DIR__.'/service/'); // 注册 service 目录下所有匿名类 $service->connectToDev(); // 连到线上测试环境
- 运行
php run.php
确保你的服务器时间准确并且线上环境需要需要支持SSL支持,执行
php --ri swoole
查看,有 openssl 表示ok,或执行php -a
输入echo SWOOLE_SSL;
有512数字表示OK
Dockerfile
FROM php:7.3-cli RUN sed -ri "s/(httpredir|deb|security).debian.org/mirrors.aliyun.com/g" /etc/apt/sources.list RUN apt-get update \ && apt-get install -y libyaml-dev libssl-dev curl librdkafka-dev net-tools iputils-ping git RUN docker-php-ext-install -j$(nproc) mysqli pdo pdo_mysql \ && pecl install msgpack \ && pecl install redis \ && pecl install yaml \ && pecl install hprose \ && docker-php-ext-enable msgpack redis yaml hprose RUN git clone --recursive --depth=1 https://github.com/kjdev/php-ext-snappy.git \ && cd php-ext-snappy \ && phpize && ./configure && make && make install \ && docker-php-ext-enable snappy # 可指定版本,例如 pecl install swoole-4.4.16 RUN printf "no\nyes\n" | pecl install swoole \ && docker-php-ext-enable swoole \ # && echo "swoole.use_shortname = 'Off'" >> /usr/local/etc/php/conf.d/docker-php-ext-swoole.ini COPY . /usr/src/server WORKDIR /usr/src/server CMD [ "php", "./bin/server.php"]
更多使用方法
<?php // run.php use XDApp\ServiceReg\Service; // 其中 demo 为项目名(AppName),test 为服务名(ServiceName),123456 为密钥 $service = Service::factory('demo', 'test', '123456'); // 1. 注册一个前端页面可访问的abc()方法 $service->addWebFunction(function($arg) { var_dump($arg); return true; }, 'abc'); // 2. 将一个文件夹的所有php文件注册进服务,支持子文件夹,php文件名为服务器名前缀, // php内返回一个闭包 fuction 或一个匿名 class,返回的匿名class的所有方法名会被注册,参考 service/sys.php // 单个方法推荐使用1,多个方法推荐2 // 3. 使用 addFunction 注册方法 // 请注意,只有服务名相同的前缀rpc方法才会被页面前端调用到 $service->addFunction(function($arg) { // 获取 context 对象 $context = Service::getCurrentContext(); var_dump($context->adminId); return true; }, 'test_abc'); // 连接到生产环境(国内) //$service->connectToProduce(); // 连接到生产环境(海外东南亚) //$service->connectToProduceAsia(); // 连接到欧洲生产环境 //$service->connectToProduceEurope(); // 或 连接到本地测试开发服务器 //$service->connectToLocalDev('127.0.0.1', 8082); // 或 连接到外网测试服务器 //$service->connectToDev(); // RPC调用远端方法,需要XDApp支持后可用 $list = $service->xdAppService()->my->getMenu(); // 等同如下: // $list = $service->service()->xdapp->my->getMenu(); // print_r($list);
更多的使用方法see: https://github.com/hprose/hprose-php/wiki/06-Hprose-服务器
服务环境
区域 | 环境 | 使用方法 |
---|---|---|
国服 | 生产环境 | connectToProduce() |
东南亚正式服 | 生产环境 | connectToProduceAsia() |
欧洲正式服 | 生产环境 | connectToProduceEurope() |
DEV测试环境 | 测试环境 | connectToDev() |
本地测试环境 | 测试环境 | connectToLocalDev() |
关于 context
上下文对象
在RPC请求时,如果需要获取到请求时的管理员ID等等参数,可以用此获取,如上面 hello
的例子,通过 $context = Service::getCurrentContext()
可获取到 context
,包括:
参数 | 说明 |
---|---|
service | 当前服务 |
client | 通信的连接对象,可以使用 close() 方法关闭连接 |
requestId | 请求的ID |
appId | 请求的应用ID |
serviceId | 请求发起的服务ID,0表示XDApp系统请求,1表示来自浏览器的请求 |
adminId | 请求的管理员ID,0表示系统请求 |
userdata | 默认 stdClass 对象,可以自行设置参数 |
更多参数见 XDApp\ServiceReg\Context
对象
Service
常用方法如下:
connectToProduce()
连接到生产环境,将会创建一个异步tls连接接受和发送RPC数据,无需自行暴露端口,如果遇到网络问题和服务器断开可以自动重连,除非是因为密钥等问题导致的断开将不会重新连接
connectToDev($serviceKey = null)
同上,连接到研发环境, 不设置 serviceKey 则使用 new ServiceAgent 时传入的密钥
connectToLocalDev($host = '127.0.0.1', $port = 8061, $serviceKey = null)
同上,连接到本地研发服务器,请下载 XDApp-Local-Dev 本地开发工具,https://github.com/xdapp/xdapp-local-dev ,启动服务
addWebFunction($function, $alias = null, $option = [])
注册一个前端web页面可访问的RPC方法到服务上,它是 service.addFunction()
方法的封装,差别在于会自动对 alias
增加 serviceName
前缀
$service->addWebFunction(hello, 'hello')
相当于 $service->addFunction(hello, 'servicename_hello')
addFunction($function, $alias = null, $option = [])
注册一个RPC方法到服务上
addHttpApiProxy($url, $alias = 'api', $methods = ['get'], array $httpHeaders = [])
添加一个http代理
使用场景: 当服务器里提供一个内部Http接口,但是它没有暴露给外网也没有权限验证处理,但希望Web页面可以使用 此时可以使用此方法,将它暴露成为一个XDApp的RPC服务,在网页里直接通过RPC请求将数据转发到SDK请求后返回,不仅可以实现内网穿透功能还可以在Console后台设置访问权限。
每个Http代理请求都会带以下头信息,方便业务处理:
- X-Xdapp-Proxy: True
- X-Xdapp-App-Id: 1
- X-Xdapp-Service: demo
- X-Xdapp-Request-Id: 1
- X-Xdapp-Admin-Id: 1
$this->addHttpApiProxy('http://127.0.0.1:9999', 'myApi', ['get', 'post', 'delete', 'put'])
Vue页面使用
方法接受3个参数,$uri, $data, $timeout,其中 $data 只有在 post 和 put 有效,$timeout 默认 30 秒
// 其中gm为注册的服务名 this.$service.gm.myApi.get('/uri?a=arg1&b=arg2'); // 最终将会请求 http://127.0.0.1:9999/uri?a=arg1&b=arg2 // 返回对象 {code: 200, headers: {...}, body: '...'} // 使用post, 第2个参数接受string或字符串, 第3个参数可设置超时 this.$service.gm.myApi.post('/uri?a=1', {a:'arg1', b:'arg2'}, 15);
addMissingFunction(function, $option = [])
此方法注册后,所有未知RPC请求都降调用它,它将传入2个参数,分别是RPC调用名称和参数
setVersion($ver)
设置服务器版本,在 Console 中的服务管理里可以看到,默认为 1.0
setLogger(callable $logger)
设置一个log处理方法,方法接受3个参数,分别是:
$type
- 类型,包括:log, info, debug, warn$msg
- Log内容,字符串或Exception对象$data
- 数组数据,可能是 null
addFilter() / removeFilter()
过滤器
可以方便开发调试
see https://github.com/hprose/hprose-php/wiki/11-Hprose-过滤器
Sentry支持
首先需要安装 sentry : composer require sentry/sdk
, 然后 XDApp\ServiceReg\Service::sentryInit('https://<key>@<organization>.ingest.sentry.io/<project>');
即可
更多参数见 https://docs.sentry.io/error-reporting/configuration/?platform=php