From f8c5a73c6b8f2f7d815ca2bf1a62fe3e97dac9a4 Mon Sep 17 00:00:00 2001 From: antao Date: Tue, 19 Mar 2019 18:22:15 +0800 Subject: [PATCH] Update the README --- README.md | 131 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 130 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7dc51831..8a108ffe 100755 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ [![Join the chat at https://gitter.im/drogon-web/community](https://badges.gitter.im/drogon-web/community.svg)](https://gitter.im/drogon-web/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Docker image](https://img.shields.io/badge/Docker-image-blue.svg)](https://cloud.docker.com/u/drogonframework/repository/docker/drogonframework/drogon) +### Overview **Drogon** is a C++14/17-based HTTP application framework. Drogon can be used to easily build various types of web application server programs using C++. **Drogon** is the name of a dragon in the American TV series "Game of Thrones" that I really like. Drogon's main application platform is Linux. It also supports Mac OS and FreeBSD. Currently, it does not support windows. Its main features are as follows: @@ -31,4 +32,132 @@ Drogon's main application platform is Linux. It also supports Mac OS and FreeBSD * Support asynchronously reading and writing sqlite3 database based on thread pool; * Provide a convenient lightweight ORM implementation that supports for regular object-to-database bidirectional mapping; -### For more information, please visit the [wiki](https://github.com/an-tao/drogon/wiki) site +## A very simple example + +Unlike most C++ frameworks, the main program of the drogon application can be kept clean and simple. Drogon uses a few tricks to decouple the controller from the main program. The routing of controllers can be done through macros or configuration file. + +Below is the main program of a typical drogon application: + +```c++ +#include +using namespace drogon; +int main() +{ + app().setLogPath("./"); + app().setLogLevel(trantor::Logger::WARN); + app().addListener("0.0.0.0", 80); + app().setThreadNum(16); + app().enableRunAsDaemon(); + app().run(); +} +``` + +It can be further simplified by using configuration file as follows: + +```c++ +#include +using namespace drogon; +int main() +{ + app().loadConfigFile("./config.json"); + app().run(); +} +``` + +Drogon provides some interfaces for adding controller logic directly in the main() function, but unless your logic is very simple, we don't recommend using them. Instead, we create an HttpSimpleController as follows: + +```c++ +/// The TestCtrl.h file +#pragma once +#include +using namespace drogon; +class TestCtrl:public drogon::HttpSimpleController +{ +public: + virtual void asyncHandleHttpRequest(const HttpRequestPtr& req,const std::function & callback)override; + PATH_LIST_BEGIN + PATH_ADD("/test",Get); + PATH_LIST_END +}; + +/// The TestCtrl.cc file +#include "TestCtrl.h" +void TestCtrl::asyncHandleHttpRequest(const HttpRequestPtr& req, + const std::function & callback) +{ + //write your application logic here + auto resp = HttpResponse::newHttpResponse(); + resp->setBody("

Hello, world!

"); + resp->setExpiredTime(0); + callback(resp); +} +``` + +Don't be scared by the code. Most of the above programs can be automatically generated by the command line tool `drogon_ctl` provided by drogon. All the user needs to do is add their own business logic. In the example, the controller returns a `Hello, world!` string when the client accesses the `http://ip/test` URL. + +For JSON format response, we create the controller as follows: + +```c++ +/// The header file +#pragma once +#include +using namespace drogon; +class JsonCtrl : public drogon::HttpSimpleController +{ + public: + virtual void asyncHandleHttpRequest(const HttpRequestPtr &req, const std::function &callback) override; + PATH_LIST_BEGIN + //list path definitions here; + PATH_ADD("/json", Get); + PATH_LIST_END +}; + +/// The source file +#include "JsonCtrl.h" +void JsonCtrl::asyncHandleHttpRequest(const HttpRequestPtr &req, + const std::function &callback) +{ + Json::Value ret; + ret["message"] = "Hello, World!"; + auto resp = HttpResponse::newHttpJsonResponse(ret); + callback(resp); +} +``` + +Let's go a step further and create a demo RESTful API with the HttpController class, as shown below (Omit the source file): + +```c++ +/// The header file +#pragma once +#include +using namespace drogon; +namespace api +{ +namespace v1 +{ +class User : public drogon::HttpController +{ + public: + METHOD_LIST_BEGIN + //use METHOD_ADD to add your custom processing function here; + METHOD_ADD(User::getInfo, "/{1}", Get); //path is /api/v1/User/{arg1} + METHOD_ADD(User::getDetailInfo, "/{1}/detailinfo, Get); //path is /api/v1/User/{arg1}/detailinfo + METHOD_ADD(User::newUser, "/{1}", Post); //path is /api/v1/User/{arg1} + METHOD_LIST_END + //your declaration of processing function maybe like this: + void getInfo(const HttpRequestPtr &req, const std::function &callback, int userId) const; + void getDetailInfo(const HttpRequestPtr &req, const std::function &callback, int userId) const; + void newUser(const HttpRequestPtr &req, const std::function &callback, std::string &&userName); + public: + User() + { + LOG_DEBUG << "User constructor!"; + } +}; +} // namespace v1 +} // namespace api +``` + +As you can see, users can use the `HttpController` to map paths and parameters at the same time. This is a very convenient way to create a RESTful API application. + +After compiling all of the above source files, we get a very simple web application. This is a good start. for more information, please visit the **[wiki](https://github.com/an-tao/drogon/wiki)** site