loentar / ngrest

Posted 2022-11-18 Dontla

参考文章1：loentar/ngrest

参考文章2：C++ & ngrest Restful服务器开发攻略

文章目录

• • ngrest
  • 快速浏览
  • • Hello world
    • 处理简单的数据类型：
    • 处理复杂的数据类型
    • 设置 HTTP 方法和位置
  • 安装
  • 创建一个新项目
  • • 示例 1. 创建项目“计算器”和服务“计算器”：
    • 示例 2. 创建项目 `'calc'` 和两个服务 - `'org.example.Calculator'` 和 `'org.example.DivService'`：
  • 启动项目
  • 实现服务
  • 升级 ngrest

ngrest

ngrest 是一个简单的 C++ REST 框架。它具有占地空间小、速度快且非常易于使用的特点。

ngrest 允许您在Apache2、nginx或简单的 ngrest http 服务器下部署 C++ RESTful Web 服务。

ngrest 是在 C++11 上编写的，并使用 CMake 进行构建。

文档和操作方法可从Wiki获得。

快速浏览

Hello world

无需编码即可使 Hello world 服务正常工作！

（安装好ngrest后）

ngrest create HelloWorld
cd helloworld
ngrest

就这样！现在您可以浏览服务操作并使用 ngrest 服务测试器尝试 HelloWorld 服务：http://localhost:9098/ngrest/service/HelloWorld。

（不过只能在ubuntu里访问，在其他主机，使用http://192.168.1.113:9098/ngrest/service/HelloWorld也访问不了，其中192.168.1.113是ubuntu的ip；需要指定ip为本地ip才能解决：ngrestserver -l 192.168.1.113 -p 9098提示找不到ngrestserver命令，export NGREST_SERVER_IP=192.168.1.113可以用，但是貌似是临时的，重启后就失效了）

echo创建后，添加到每个服务的测试资源和地址http://localhost:9098/helloworld/echo?text=YOUR_TEXT此服务将响应：

"result": "Hi, YOUR_TEXT"

处理简单的数据类型：

ngrest 支持简单的 C++ 数据类型：

class Calculator: public ngrest::Service 
public:
    int add(int a, int b) 
        return a + b;
    

    int sub(int a, int b) 
        return a - b;
    
;

对于请求http://localhost:9098/Calculator/add?a=2&b=3这个服务会响应：

"result":5

处理复杂的数据类型

ngrest 支持复杂的 C++ 数据类型，例如结构、枚举、typedef 和 STL 容器：

struct Pet 
    enum class Species 
        canine,
        feline
    ;

    Species species;
    std::string name;
    std::string birthday;
;


class Pets: public ngrest::Service 
public:
    std::list<Pet> getPets() 
        return std::list<Pet>(
            Pet::Species::canine,
            "spot",
            "Jan 1, 2010"
        ,
            Pet::Species::feline,
            "puff",
            "July 4, 2014"
        );
    
;

对于请求http://localhost:9098/Pets/getPets，此服务将响应：

"result":["species":"canine","name":"spot","birthday":"Jan 1, 2010","species":"feline","name":"puff","birthday":"July 4, 2014"]

设置 HTTP 方法和位置

要设置 HTTP 方法和位置，请使用特殊注释：

// *location: /notes
class Notes: public ngrest::Service 
public:
    //! adds a new note
    // *method: POST
    // *location: /new
    std::string add(const std::string& text);

    //! gets all notes
    // *location: /all
    std::map<std::string, std::string> getAll();

    //! get a note by id
    // *location: /id
    std::string get(const std::string& id);

    //! deletes a note by id
    // *method: DELETE
    // *location: /id
    std::string remove(const std::string& id);
;

请注意，默认方法是GET，默认位置等于名称。

这将在根路径上创建一个 REST 服务/notes。这也将添加四个资源：

操作	方法	网址	请求	响应
add	POST	http://localhost:9098/notes/new	"text":"Example text of the note"	"result":"d90638e1"
getAll	GET	http://localhost:9098/notes/all		"result":["d90638e1":"Example text of the note"]
get	GET	http://localhost:9098/notes/d90638e1		"result":"Example text of the note"
remove	DELETE	http://localhost:9098/notes/d90638e1

安装

支持的操作系统有：Linux、Windows 和 Mac OS X。如果您需要其他操作系统的支持，请创建新问题。

Linux下的安装过程很简单。要安装 ngrest，只需打开终端并复制粘贴：

wget -qO- http://bit.ly/ngrest | bash

arnold：装不了啊，用这个方法：

git clone https://github.com/loentar/ngrest.git
cd ngrest
mkdir build
cd build
cmake ../../ngrest
make
cd ../scripts/
./inst 

能装！

带有 Linux 屏幕截图的安装指南

带有 Windows 屏幕截图的安装指南

带有 Mac OS X 屏幕截图的安装指南

笔记：

如果您没有所需的依赖项之一，安装程序将要求您输入密码以自动安装。
如果您不想这样做，请按 Ctrl+C 并启动此命令：“sudo apt-get install git cmake g++”。apt-get 完成后，重新开始上面的行。

默认情况下，脚本将ngrest包装器安装到可用的最佳位置。
如果您~/bin的搜索路径中有目录，ngrest包装器将安装到其中。
否则，它将尝试安装/usr/local/bin/，并提示您输入密码以进行安装。
要覆盖此行为并强制将ngrest包装器安装到~/bin请创建~/bin目录并重新登录。
重新登录后应该会$PATH自动添加进去。
如果这没有发生，请在您的~/.bashrc或~/.profile一行中添加：export PATH=$PATH:$USER/bin。
您也可以将USERINST环境变量导出到非空的东西，安装 ngrest 并重新登录。

创建一个新项目

如何使用屏幕截图创建和启动项目

要创建一个新项目，请打开新终端并输入：

ngrest create <project_name>

或者，如果您不希望将服务拆分为接口 (.h) 和实现 (.cpp) 并在单个文件中开发整个服务.hpp，请添加-d hpp选项，ngrest 将为您创建 hpp 样式的服务：

ngrest create -d hpp <project_name>

<project_name>您的项目名称和服务名称在哪里。

示例 1. 创建项目“计算器”和服务“计算器”：

ngrest create Calculator

您可以选择设置其他服务并定义它的命名空间。

示例 2. 创建项目 'calc' 和两个服务 - 'org.example.Calculator' 和 'org.example.DivService'：

ngrest create calc org.example.Calculator org.example.DivService

启动项目

生成项目时，echo会在每个服务中添加一个操作。它仅作为快速示例提供，可以在您编写自己的操作时安全地删除。

您可以在创建项目后立即启动项目：

cd calc
ngrest

ngrest wrapper 将构建您的项目并将在默认端口上启动服务器。

To test your services try ngrest service tester:服务器启动后，您可以尝试您的服务操作：在浏览器中打开位于消息下方的链接，单击“echo”链接，在“文本”字段中输入内容，然后按“提交”。

实现服务

服务的来源位于<servicename>/src/<ServiceName>.h/cpp/hpp文件中。要实现您的服务，您必须编辑这些文件（QtCreator 是一个非常好的工具：从 QtCreator 的项目目录中打开 CMakeLists.txt）。

当您更改源代码时，您可以让项目启动。ngrest 将检测源代码中的任何更改，并尝试构建和应用更改。如果构建成功，ngrest 将重新启动服务器。

如果您遇到崩溃，ngrest 将尝试使用 gdb 跟踪错误并显示崩溃的位置和程序堆栈。要重新启动服务器，只需修改您的源代码。

例子。在 Calculator 服务中添加“add”操作：

如果您使用 hpp 样式的服务，请将这些行插入到Calculator.hpp课程结束之前：

int add(int a, int b)

    return a + b;

使您的服务类看起来像这样：

class Calculator: public ngrest::Service

public:
    // ...
    std::string echo(const std::string& text)
    
        return "Hi, " + text;
    

    int add(int a, int b)
    
        return a + b;
    
;

如果您使用 h/cpp 样式的服务，请将此行插入到Calculator.h课程结束之前：

int add(int a, int b);

使您的服务类看起来像这样：

class Calculator: public ngrest::Service

public:
    // ...
    std::string echo(const std::string& text);

    int add(int a, int b);
;

并添加实现 - 将这些行附加到Calculator.cpp：

int Calculator::add(int a, int b)

    return a + b;

之后，单击服务测试器中的服务名称以查看并测试新add操作。

升级 ngrest

要将 ngrest 从 master 分支类型升级到最新的变更集：

ngrest upgrade

如果要降级到特定提交，请将提交哈希添加为最后一个参数，例如：

ngrest upgrade 3b78eee

如果有任何正在运行的项目，它将自动重建并重新启动。