Skip to content

xdapp/xdapp-sdk-php

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

37 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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();  // 连到线上测试环境
  1. 运行 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