Paozhu packages a C++ web stack into one build tree, ORM included

What the framework bundles and why that matters for the build

Paozhu, whose name means firecracker, describes itself as a full-stack rapid development framework for the web with the slogan born for rapid C++ web development. The README's claim is that the framework integrates a C++ ORM and delivers development speed comparable to scripting languages.

The feature list is thirty items long, and reading it as a list of subsystems is more useful than reading it as a list of features. There is a built-in web server that natively parses HTTP/1.1, HTTP/2, JSON and WebSocket protocols and handles GET and POST with distinct handling for different POST content types. There is a WebSocket server and client with full-duplex communication and built-in push to connected clients. There is an HTTP client with GET and POST in both synchronous and asynchronous modes. There is an ORM for MySQL, PostgreSQL, SQLite and MariaDB, working in coroutine and synchronous modes. There are two separate thread pools, one for the framework and one for user programs, and the whole thing is built on Asio coroutines with IO running across both coroutine pools and thread pools.

Then there is the long tail: a micro-object called obj_val that stores char, int, string and float data and receives parsed URL and POST parameters, a cache module that can hold ORM query results, a plugin module with hot module replacement, gzip and Brotli output compression, ACME integration for automatic certificate renewal and OCSP stapling, PHP-FPM FastCGI support, an RPC server and client, MQTT with SSL, an integrated SendMail library, QR code, CAPTCHA and SVG chart generation, Excel and Word handling, image processing, an HTML-to-PDF module, ZIP archives, WeChat Mini Program payment, and rate limiting on a 60-second moving average.

The runtime requirements are short: C++20, and Asio, OpenSSL, Zlib and Brotli, on Linux, macOS or Windows. The repository top level shows the size of the thing, with directories for common, conf, controller, docker, docs, libs, mqtt, orm, redis, schema, sockets, startup, tests, vendor, view, viewsrc, websockets and www, plus an xmake.lua and a vcpkg configuration, and an asio.zip that ships the dependency in the tree.

The trade is stated plainly: you get a lot of functionality without choosing and integrating a dozen libraries, and you get a framework that owns your project layout, your entity definitions and your URL mapping.

Annotations in controller files and generated ORM entities

Two mechanisms do most of the work in the rapid development claim, and both are worth understanding before you commit.

The first is annotation extraction. The README says that annotations in controller .cpp files are automatically extracted for URL mapping, and that all business logic entry points belong under controller/src. The Hello World example lives at controller/src/testhello.cpp and includes orm.h, httppeer.h and the generated testhello.h, and opens a namespace called h. The build extracts the annotations, turns them into routes, and generates the header for the controller.

The second is ORM code generation. The README states that the ORM auto-generates C++ entity code from the database, so no manual coding is needed for model definitions. A models directory at the repository root and a schema directory suggest the workflow: point the tool at a database, and the C++ entity types are produced for you.

Both of these are conveniences that also constrain you. Generated entity code means the C++ class for a table is not hand-written, so the database is the source of truth for your types, and a schema change becomes a regeneration step rather than an edit. Annotation extraction means your routes live in comments or attributes inside the controller implementation rather than in a separate registration file, which keeps related code together and also means a mistake in an annotation is a routing bug that is not obvious from the file list.

The JSON side has a parallel mechanism. The README lists struct and class annotations for JSON serialization through json_encode and json_decode, and separately lists JSON encoding and decoding with zero third-party dependencies and full compliance with JSON standards. A framework that ships its own JSON implementation avoids a dependency but also owns the edge cases your data will eventually hit.

Building the project on Linux, macOS and Windows

Installation means putting Asio in the tree and running CMake. The README says to unzip asio.zip into the project root, or download the latest Asio release and place it there, and the expected layout is:

|-vendor
|-CMakeLists.txt
|-asio
  |-asio
  |-asio.hpp

The build itself is the standard CMake sequence, in a build directory outside the source tree:

mkdir build
cd build
cmake ..
make

For production the README asks for a Release build, and the parallelism flag is the only extra hint:

cmake .. -DCMAKE_BUILD_TYPE=Release
make -j8

Dependency installation differs per platform, and macOS is the shortest list, through Homebrew:

brew install asio
brew install cmake
brew install openssl
brew install zlib
brew install brotli

On Ubuntu and Fedora the same set is installed with apt-get, along with a MySQL server, and the README notes the systems are tested on Ubuntu 22.04 or later and Fedora 38, with ASAN installed on Fedora through the yum package manager. The Windows path has two variants, xmake and vcpkg. The xmake route requires editing conf/server.conf to replace a hardcoded project path before building:

paozhu-main> xmake
paozhu-main> .\build\windows\x64\release\paozhu.exe

The vcpkg route downloads a specific vcpkg release, bootstraps it, and integrates it, and the CMake configure then points at the vcpkg toolchain file with a Windows triplet:

cmake . -B ${{github.workspace}} -DENABLE_WIN_VCPKG=ON -DENABLE_VCPKG=ON ^
    -DCMAKE_TOOLCHAIN_FILE=vcpkg-2023.12.12/scripts/buildsystems/vcpkg.cmake ^
    -DVCPKG_TARGET_TRIPLET=x64-windows -DCMAKE_BUILD_TYPE=Debug -G Ninja

The asio.zip in the repository root is worth a second look. Shipping your dependency as a zip in the tree removes a version negotiation step, at the cost of a vendored copy you are responsible for keeping current.

Running the server, mapping hosts and the annotation-driven routes

The configuration file is conf/server.conf, and it holds a mainhost value that you note first, then replace any hardcoded project paths with your own, since the README warns about a literal /Users/hzq/paozhu path that has to be swapped for your own project path.

Hosts configuration follows. You edit the hosts file and append a line mapping your domain to loopback:

sudo vim /etc/hosts

127.0.0.1 www.yourdomain.com

Then the server is started, and the README calls this the HTTPS test section even though the URLs it lists are plain HTTP:

sudo ./bin/paozhu

With that running, a browser is pointed at localhost or at your mapped domain. The framework serves the www directory as static content and dispatches everything else through the annotated controllers.

For a real look at the routing model, the README points at the controller directory, which it says contains full CRUD operations. That is the part to read first if you are evaluating the framework, because the generated admin backend at /admin/main and the CRUD controllers show what a real application looks like under the annotation mapping, and the view and viewsrc directories suggest a template layer where the views live in one place and the code that renders them in another.

The admin backend demo and the RPC server and client, which uses HTTP-annotated URL functions, point in the same direction. The framework is trying to make a single annotation vocabulary serve for pages, for API endpoints and for remote procedure calls, and that is a coherent idea even if it is a large surface to hold in your head.

Benchmarking requires an explicit flag and disabling rate limiting

The README includes a stress testing section, and it contains one of the more useful pieces of operational advice in the whole document: the framework has rate limiting enabled by default, and that must be turned off for the numbers to mean anything.

To use h2load or ab you need a benchmark build, which is a CMake option:

cmake .. -DCMAKE_BUILD_TYPE=Release -DENABLE_BENCHMARK=ON

Three commands are then offered. The Apache benchmark tool against a plain HTTP endpoint, a much smaller request count with h2load against HTTPS, and a bundled webbench binary with a concurrency and time budget:

ab -n 120000 -c 20 http://www.xxx.com

h2load -n 12000 -c 100 -m 10 https://www.xxx.com

./webbench -c 300 -t 59 http://www.xxx.com/cms/list

Note the shape of the request counts. The ab run asks for 120000 requests with 20 concurrent connections, the h2load run asks for 12000 requests with 100 connections and 10 multiplexed streams, and webbench asks for 300 concurrent clients over 59 seconds against a CMS listing route. Those are the workloads the author had in mind, and the CMS list route is a realistic one rather than a static file.

No results are published in the README, and the repository carries a Benchmark directory, so any figure you see attributed to this framework came from running it yourself. What the README does give you is the honest setup advice, which is more than most project documentation manages.

Where a framework this wide is the wrong choice

There are several reasonable reasons to walk away, and they are not about missing features.

The first is surface area. A framework that owns your HTTP server, your websocket layer, your database mapping, your templating, your caching, your mail, your image processing, your PDF generation and your payment integration is a framework where a single upstream behaviour change can affect parts of your application you did not know were coupled. A service that only needs a JSON API and one database table is paying for the entire list.

The second is the code generation and annotation model. If your team prefers explicit routing and hand-written types, the framework's central conveniences are costs. And because the entity code is generated from the database, a schema-first workflow is enforced on you, which is not how every team works.

The third is the platform floor. C++20 is required, and the README lists macOS Sequoia or later, Ubuntu 22.04 or later and Fedora 38 as the tested systems. That is a modern floor, and it rules out older enterprise images, which is a common deployment environment for the kind of service this framework targets.

The fourth is the build story on Windows, which requires editing a config file to replace a hardcoded path, then either xmake or a specific vcpkg release with a toolchain file. The README is honest about this, but it is friction that a mature team will spend a day on.

The alternative approach, and it is a real one, is to pick a smaller C++ HTTP library and a separate database layer, and to own the composition yourself. The difference in approach is precisely the point of this framework: Paozhu trades composability and control for completeness and speed of delivery, and a team that has the expertise to compose its own stack gets a smaller dependency surface and a codebase where every layer is understood.

Editorial conclusion

Adopt Paozhu if you are building a C++ service that needs a web layer, a database mapper and websocket support in one dependency, and if you are comfortable with a framework that decides the directory layout, the entity generation and the annotation mapping for you. Do not adopt it for a library you intend to publish, for a service with a small team that would rather own its HTTP and database layers separately, or if you need a framework that can be audited in an afternoon, because the repository is very large and the last push was on 2026-10-22 with a 1.17.x release line. Verify first that your compiler supports C++20 and that Asio, OpenSSL, Zlib and Brotli are available, that the ORM code generation produces the entity code you expect before you build on it, and that the annotations in your controller files are extracted into the URL mapping as the README claims.

Frequently asked questions

Official sources

1. hggq/paozhu on GitHub
2. Issues
3. License: MIT
4. README
5. Releases