3.4 C++ Rest 服务 API 自动实现

        本文是 《基于 Qt 的 REST 网络框架》的其中一节，建议全章阅读。

---

        使用过 Java Retrifit 的人，一定对它的简单易用感到惊叹。它的“声明即实现”的思想，让所有人都觉得耳目一新。

public interface GitHubService {
  @GET("users/{user}/repos")
  Call<List<Repo>> listRepos(@Path("user") String user);
}

        如何在 C++ 中也做到这样的效果呢？本文的目标就是提供一个实现思路。

        在 C++ 中没有类似 Java 的动态代理，不能在运行时创造出一个接口的实现类，即使用 lambda 表达式也是在编译期就确定了。

        想要在普通类（非虚拟类）的上面定义方法，但是又不实现这些方法，是不可能的。那么还有什么可以像方法那样的使用呢，我们想到了函数对象。沿着这个思路下去，我们创造出了一套可行的“声明即实现”的路径。

Rest 函数参数

        在介绍 Rest 函数对象之前，有必要先讨论一下其参数形式。形如

QTestData test(char const * queryK1, char * headerH1)

的方法 test，其中 queryK1 传递给 URI 的 query（?k1=<queryK1>），headerH1 传递给头域（h1: <headerH1>），那么怎么表示参数的目标呢？

        我们的方案是定义一系列辅助类，它们派生于统一基类 QRestArg，基类是这样定义的：

class QRestArg
{
public:
    virtual void apply(QRestJson & json, QRestRequest & req) const;
    virtual void apply(QRestRequest & req) const { (void) req; }
};

        也就是说，具体怎么使用参数，由不同的派生类自定义实现。比如要将参数填充到 Query 中，就有 QQueryBase 类：

class QQueryBase : public QRestArg
{
public:
    QQueryBase(char const * name, QString value);
private:
    virtual void apply(QRestRequest & req) const
    {
        req.url_query().addQueryItem(name_, value_);
    }
private:
    char const * name_;
    QString value_;
};

        但是 query 名称（name）应该是预置固定的，所以用模版参数来固化名称：

template <char const * const N, typename T = QVariantEx>
class QQuery : public QQueryBase
{
public:
    typedef T type;
    QQuery(T const & value)
        : QQueryBase(N, QVariantEx(value).toString())
    {
    }
};

        最后，在声明 test 方法时，需要使用下面的形式：

static constexpr char const K1[] = "k1";
static constexpr char const H1[] = "h1";
QTestData test(QQuery<K1, char const *>, QHeader<H1, char const *>)

Rest 函数

        接下来就是 Rest 函数如何实现了。很简单，就是这样的：

template<template<typename> class R, typename T, typename ...Args>
class Function<R, T (Args...)> : FunctionBase
{
public:
    Function(QRestService * service, QRestRequest::Method method, char const * path)
        : FunctionBase(service, method, path)
    {
    }
    QtPromise::QPromise<T> operator()(Args const & ...args) const
    {
        QRestRequest request(method_, path_, args...);
        return service_->client_->request<R, T>(request);
    }
};

        模版参数 R 表示 统一的 Result 报文格式（比如 code，msg，data 字段），模版参数 T 表示该接口方法实际返回的数据类型（即 data 的类型），模版参数 Args 就是一系列接口方法参数了。（关于这个可变参数如何使用，请参考源代码，限于篇幅，这里就不展开了）

        有了上面的基础，声明一个接口方法就很简单了，比如：

class QTestService : public QRestService
{
public:
    Function<QTestResultT, QTestData(QQuery<K1, char const *>, QHeader<H1, char const *>)> test(this, Method::Get, "test/v1");
};

        这里的 "test/v1" 是服务端的 API 端点（路径）。

        如果觉得有点长的话，可以用宏封装一下：

class QTestService : public QRestService
{
public:
    Q_REST_GET("test/v1", test, QTestData(QQuery<K1, char const *>, QHeader<H1, char const *>))
};

        怎么样，是不是与 retrifit 差不多了。使用起来也是很简单的：

QTestService service;
service.test("query1", "header1").then([] (QTestData data) {
    qDebug() << data;
}).tapFail([](std::exception & e) {
    qDebug() << e.what();
}).wait();

使用弱类型调用 API

        弱类型帮助减少耦合，在某些场合（比如 webjs）必须使用弱类型，所以我们的 Rest API 也要支持弱类型调用。

        目标就是实现这样一个方法：

class QTRESTCLIENT_EXPORT QRestService : public QObject
{
    Q_OBJECT
public:
    QtPromise::QPromise<QVariant> invoke(QByteArray const & func, QVariant const & args);
};

        基于之前的 API 自动生成，我们很容易增加一些代码，收集到所有的 API 方法：

QRestService::FunctionBase::FunctionBase(QRestService *service, QRestRequest::Method method, const char *path, const char *func, QRestService::FunctionBase::invoke_t invoke)
    : service_(service)
    , method_(method)
    , path_(path)
    , invoke_(invoke)
{
    service_->functions_.insert(func, this);
}

        这里的 invoke 方法的实现利用了 QVariant 的类型转换，它与前面《消息总线中的弱类型处理》中介绍的 QSubscriber::invoke 差不多，这里就不再展开了。