srpc/tools/README_cn.md

English version

srpc小工具

一个帮你快速生成Workflow和SRPC项目的脚手架小工具。

1. 编译

先从github上把srpc项目拷贝下来，小工具代码在srpc/tools/目录下，执行make即可编译。

git clone https://github.com/sogou/srpc
cd srpc/tools
make

2. 用法

执行./srpc即可看到小工具的用法介绍：

./srpc

Description:
    Simple generator for building Workflow and SRPC projects.

Usage:
    ./srpc <COMMAND> <PROJECT_NAME> [FLAGS]

Available Commands:
    http    - create project with both client and server
    redis   - create project with both client and server
    rpc     - create project with both client and server
    api     - create protobuf or thrift IDL api
    proxy   - create proxy for some client and server protocol
    file    - create project with asynchronous file service
    compute - create project with asynchronous computing service

3. 入门

我们先从最简单的命令开始入门：

./srpc http project_name1

然后就可以看到屏幕上显示，项目建立在了新目录project_name1/中，并且带有编译和执行的提示命令。

Success:
      make project path project_name1/ done.

Commands:
      cd project_name1/
      make -j

Execute:
      ./server
      ./client

打开目录，我们查看一下有什么文件：

cd ./project_name1/ && tree

.
├── CMakeLists.txt
├── GNUmakefile
├── client.conf
├── client_main.cc
├── config
│   ├── Json.cc
│   ├── Json.h
│   ├── config.cc
│   ├── config.h
│   └── util.h
├── full.conf
├── server.conf
└── server_main.cc

2 directories, 12 files

然后我们就可以根据上面执行srpc命令时所看到的指引，编译和执行这个项目。

4. HTTP

创建HTTP项目的用法如下，可以创建http协议的server和client。其中server和client里的示例代码都可以自行改动，配置文件server.conf和client.conf里也可以指定基本的配置项，cmake编译文件都已经生成好了，整个项目可以直接拿走使用。

./srpc http

Missing: PROJECT_NAME

Usage:
    ./srpc http <PROJECT_NAME> [FLAGS]

Example:
    ./srpc http my_http_project

Available Flags:
    -o :    project output path (default: CURRENT_PATH)
    -d :    path of dependencies (default: COMPILE_PATH)

5. RPC

创建RPC项目的用法如下，包括了多种rpc协议，protobuf或thrift的文件：

./srpc rpc

Missing: PROJECT_NAME

Usage:
    ./srpc rpc <PROJECT_NAME> [FLAGS]

Example:
    ./srpc rpc my_rpc_project

Available Flags:
    -r :    rpc type [ SRPC | SRPCHttp | BRPC | Thrift | ThriftHttp | TRPC | TRPCHttp ] (default: SRPC)
    -o :    project output path (default: CURRENT_PATH)
    -s :    service name (default: PROJECT_NAME)
    -i :    idl type [ protobuf | thrift ] (default: protobuf)
    -x :    data type [ protobuf | thrift | json ] (default: idl type. json for http)
    -c :    compress type [ gzip | zlib | snappy | lz4 ] (default: no compression)
    -d :    path of dependencies (default: COMPILE_PATH)
    -f :    specify the idl_file to generate codes (default: template/rpc/IDL_FILE)
    -p :    specify the path for idl_file to depend (default: template/rpc/)

我们通过以下命令，试一下指定要创建的RPC项目所依赖的proto文件：

./srpc rpc rpc_example -f test_proto/test.proto 

然后就可以看到一些生成代码多信息，这和原先使用srpc_genrator时所看到的是类似的。

Info: srpc generator begin.
proto file: [/root/srpc/tools/rpc_example/test.proto]
Successfully parse service block [message] : EchoRequest
Successfully parse service block [message] : EchoResponse
Successfully parse service block [service] : new_test
Successfully parse method:Echo req:EchoRequest resp:EchoResponse
finish parsing proto file: [/root/srpc/tools/rpc_example/test.proto]
[Generator] generate srpc files: /root/srpc/tools/rpc_example/test.srpc.h 
[Generator Done]
[Generator] generate server files: /root/srpc/tools/rpc_example/server_main.cc, client files: /root/srpc/tools/rpc_example/client_main.cc
Info: srpc generator done.

Success:
      make project path rpc_example/ done.

Commands:
      cd rpc_example/
      make -j

Execute:
      ./server
      ./client

6. API

API命令用于简单地创建一个IDL文件，这样方便我们改完文件之后再进行rpc项目调查创建。命令如下：

Missing: FILE_NAME

Usage:
    ./srpc api <FILE_NAME> [FLAGS]

Example:
    ./srpc api my_api

Available Flags:
    -o : file output path (default: CURRENT_PATH)
    -i : idl type [ protobuf | thrift ] (default: protobuf)

我们通过以下命令，可以创建一个默认为proto格式的文件：

./srpc api test

Success:
      Create api file test.proto at path /root/srpc/tools done.

Suggestions:
      Modify the api file as you needed.
      And make rpc project base on this file with the following command:

      ./srpc rpc my_rpc_project -f test.proto -p /root/srpc/tools

之后就可以通过以上建议的命令创建一个rpc项目了，rpc项目以test.proto文件创建生成代码，使用方法如RPC部分介绍。

7. REDIS

创建REDIS协议的client和server，命令如下：

./srpc redis

will get the following instructions:

Missing: PROJECT_NAME

Usage:
    ./srpc redis <PROJECT_NAME> [FLAGS]

Example:
    ./srpc redis my_redis_project

Available Flags:
    -o :    project output path (default: CURRENT_PATH)
    -d :    path of dependencies (default: COMPILE_PATH)

根据以上指引我们创建了一个项目后，就可以得到最简单的redis server和client。client就简单地实现了发送SET k1 v1命令，而server无论收到什么都会简单地回复一个OK。我们可以用这简单的示例，改造一个可以请求任何redis协议服务的client，也可以构造一个简单的redis服务器。

./server

Redis server start, port 6379
redis server get cmd: [SET] from peer address: 127.0.0.1:60665, seq: 0.

./client

Redis client state = 0 error = 0
response: OK

如果client有填写用户名和密码的需求，可以填到client.conf中。我们打开这个配置文件看看：

  1 {
  2   "client":
  3   {
  4     "remote_host": "127.0.0.1",
  5     "remote_port": 6379,
  6     "retry_max": 2,
  7     "user_name": "root",
  8     "password": ""
  9   }
 10 }

8. PROXY

这个命令用于构建一个转发服务器，并且还有与其协议相关的server和client。

./srpc proxy

执行上述命令，我们可以看到proxy命令的指引：

Missing: PROJECT_NAME

Usage:
    ./srpc proxy <PROJECT_NAME> [FLAGS]

Example:
    ./srpc redis my_proxy_project

Available Flags:
    -c :    client type for proxy [ Http | Redis | SRPC | SRPCHttp | BRPC | Thrift | ThriftHttp | TRPC | TRPCHttp ] (default: Http)
    -s :    server type for proxy [ Http | Redis | SRPC | SRPCHttp | BRPC | Thrift | ThriftHttp | TRPC | TRPCHttp ] (default: Http)
    -o :    project output path (default: CURRENT_PATH)
    -d :    path of dependencies (default: COMPILE_PATH)

让我们来试一下，创建一个转发不同协议的项目：

./srpc proxy srpc_trpc_proxy_example -c SRPC -s TRPC

Success:
      make project path srpc_trpc_proxy_example/ " done.

Commands:
      cd srpc_trpc_proxy_example/
      make -j

Execute:
      ./server
      ./proxy
      ./client

查看新创建的项目中有什么文件：

cd srpc_trpc_proxy_example && tree

.
├── CMakeLists.txt
├── GNUmakefile
├── client.conf
├── client_main.cc
├── config
│   ├── Json.cc
│   ├── Json.h
│   ├── config.cc
│   └── config.h
├── proxy.conf
├── proxy_main.cc
├── server.conf
├── server_main.cc
└── srpc_trpc_proxy_example.proto

2 directories, 13 files

分别在三个终端执行./server ./proxy 和 ./client，我们可以看到，client发送了trpc协议的请求"Hello, this is sync request!" 和一个异步请求Hello, this is async request!"给proxy，而proxy收到之后把请求用srpc协议发给了server。SRPC server填了回复"Hi back"并通过刚才的proxy路线转回给了client，期间转发纯异步，不会阻塞任何线程。

./server

srpc_trpc_proxy_example TRPC server start, port 1412
get req: message: "Hello, this is sync request!"
get req. message: "Hello, this is async request!"

./proxy

srpc_trpc_proxy_example [SRPC]-[TRPC] proxy start, port 1411
srpc_trpc_proxy_example proxy get request from client. ip : 127.0.0.1
message: "Hello, this is sync request!"
srpc_trpc_proxy_example proxy get request from client. ip : 127.0.0.1
message: "Hello, this is async request!"

./client

sync resp. message: "Hi back"
async resp. message: "Hi back"

9. FILE

这是一个简单的文件服务器，文件读取都是异步的，不会因为读文件阻塞当前服务器的处理线程：

./srpc file file_project

Success:
      make project path file_project/ done.

Commands:
      cd ./file_project/
      make -j

Execute:
      ./server

Try file service:
      curl localhost:8080/index.html
      curl -i localhost:8080/a/b/

我们通过上述命令创建之后，可以看看文件服务器的目录结构如下：

.
├── CMakeLists.txt
├── GNUmakefile
├── config
│   ├── Json.cc
│   ├── Json.h
│   ├── config.cc
│   └── config.h
├── file_service.cc
├── file_service.h
├── html
│   ├── 404.html
│   ├── 50x.html
│   └── index.html
├── server.conf
└── server_main.cc

3 directories, 13 files

打开server.conf，就可以看到我们为文件服务器添加的具体配置项：root和error_page。我们可以通过root去指定打开文件的根目录，以及通过error_page去关联具体的错误码和它们所要返回作body的页面名称。

  1 {
  2   "server":
  3   {
  4     "port": 8080,
  5     "root": "./html/",
  6     "error_page" : [
  7       {
  8         "error" : [ 404 ],
  9         "page" : "404.html"
 10       },
 11       {
 12         "error" : [ 500, 502, 503, 504],
 13         "page" : "50x.html"
 14       }
 15     ]
 16   }
 17 }

我们执行make进行编译，然后执行./server把文件服务器跑起来，然后用curl进行测试：

示例1：在根目录./html/下读取文件index.html（即使请求localhost:8080，默认也是读index.html）。

curl localhost:8080/index.html

<html>Hello from workflow and srpc file server!</html>

示例2：读文件/a/b/，这个文件不存在，所以我们根据上面配置文件server.conf中所指定的，填入404错误码会返回页面404.html的内容。

curl -i localhost:8080/a/b/
HTTP/1.1 404 Not Found
Server: SRPC HTTP File Server
Content-Length: 59
Connection: Keep-Alive

<html>This is not the web page you are looking for.</html>

以下信息在server端可以看到：

./server 
http file service start, port 8080
file service get request: /a/b/

10. COMPUTE

接下来是一个简单的计算服务器，同理，计算也不会阻塞当前服务器的处理线程：

./srpc compute compute_test

通过以上命令，我们可以创建一个小项目，项目默认接收url请求作为参数n，并进行斐波那契计算。

Success:
      make project path compute_test/ done.

Commands:
      cd compute_test/
      make -j

Execute:
      ./server

Try compute with n=8:
      curl localhost:8080/8

进入compute_test/目录执行make，并执行./server运行起来。然后我们就可以使用curl或者浏览器输入localhost:8080/8，计算第8个斐波那契数是多少。这里以curl为例：

curl localhost:8080/8

<html><p>0 + 1 = 1.</p><p>1 + 1 = 2.</p><p>1 + 2 = 3.</p><p>2 + 3 = 5.</p><p>3 + 5 = 8.</p><p>5 + 8 = 13.</p><p>The No. 8 Fibonacci number is: 13.</p></html>

我们看到了server内部的计算步骤。server的计算例子使用了go_task去封装一个计算函数，欢迎尝试更多的计算调度。