第11章：通用库：POCO 集成

网络、JSON、数据库，一次打包——跟着狄仁杰把 POCO 这套 C++ 综合类库从源码编译到第一个程序完整走一遍

11.1 零基础铺垫：为什么 C++ 需要通用库

前几章我们装过 jsoncpp、spdlog，都是解决单个问题的小库；这一章要上一个"全家桶"。通用库（general-purpose library）说人话：把网络、JSON、数据库、日志、配置文件这些几乎每个程序都要用的能力，预先写好、打包成一套互相配合的库。为什么需要它？因为 C++ 标准库只管语言地基——容器、算法、字符串、文件流——而 HTTP 客户端、JSON 解析、MySQL 连接这些"通用能力"全都不在标准库里。第 6 章已经验证过：JSON 得靠库；网络和数据库同样如此。如果每个项目都从零手写一遍网络层，等于每家餐厅都自己种小麦，既不现实也养不起。

不用通用库的代价有多大？我们只看一个最简单的动作——"向服务器发一个 HTTP GET 请求"。你要自己拼请求行、处理各种状态码、解析响应头、处理连接断开……第 6 章手动解析 JSON 的教训还热乎着，网络协议比 JSON 只难不简单。下面的"错误示范"只展示了冰山一角，真实的手写实现动辄几百行还到处是边界 bug：

// 示意：想手写一个 HTTP GET，第一关就劝退——
// 请求行、请求头、空行、Host 头，一个都不能错
int sock = socket(AF_INET, SOCK_STREAM, 0);
// connect() 到 80 端口……（此处省略十几行地址结构体代码）
std::string req = "GET /json HTTP/1.1\r\n"
                + "Host: example.com\r\n"
                + "Connection: close\r\n\r\n";
send(sock, req.c_str(), req.size(), 0);
// recv() 循环收数据、解析状态行、解析响应头……（再省略五十行）
// 遇到 301 重定向？分块传输？连接被服务器关闭？自己扛吧

同样的活，交给 POCO 之后长这样——连服务器、发请求、收响应，每步一行。差别不只是"行数少"，而是正确性不用自己操心：协议细节、错误处理、跨平台差异，全在库内部消化掉了：

// 同一个 GET 请求，POCO 版（完整可运行代码见 11.6 节）
Poco::Net::HTTPClientSession session("example.com");   // 连上服务器
Poco::Net::HTTPRequest req(Poco::Net::HTTPRequest::HTTP_GET,
    "/", Poco::Net::HTTPMessage::HTTP_1_1);             // 构造请求
session.sendRequest(req);                               // 发出请求
Poco::Net::HTTPResponse res;
std::istream& body = session.receiveResponse(res);        // 收响应

用通用库之后，这段"劝退代码"会缩成一个类、三行调用——这正是 11.6 节第一个 POCO 程序的样子。而且通用库的价值不只是省代码：它把跨平台也一并解决了。同一个 Poco::Net::HTTPClientSession，在 Linux、macOS、Windows 上行为一致，底下的 socket 差异全被库消化。这一章的主角 POCO，就是 C++ 生态里最有名的综合类库之一，官方定位是"构建网络和互联网应用的跨平台 C++ 类库"。

11.2 POCO 是什么：把常用能力打包的综合类库

POCO（Portable Components）是一套开源的 C++ 综合类库——说人话：它把网络、JSON、XML、数据库、日志、进程线程等常用能力按主题拆成一个个独立模块，你用哪块就编译哪块，像搭积木一样按需组合。它托管在 github.com/pocoproject/poco，采用 Boost Software License 1.0（BSL-1.0）许可，可以自由商用。POCO 只发布源码，没有官方二进制包（官网明确说明），所以"自己编译"是每个 POCO 用户的必修课——这也正是本章的核心实战。它的模块化设计很符合狄仁杰的系统分析方法：先看清整个系统由哪些部分组成、各自管什么。

先看 POCO 的模块地图。记住一条主线：Foundation 是地基，其他所有模块都站在它上面。地基提供字符串、文件、日志、线程、时间这些最基础的能力；Net 负责网络；JSON 和 XML 负责数据交换格式；Data 是数据库的统一访问层，下面再接 MySQL、SQLite 等具体连接器：

POCO 的源码目录结构也按模块分得很清楚，每个模块一个顶层目录，各自带着 include/（头文件）、src/（源码）和 samples/（示例）。想快速上手一个模块，先翻它的 samples 是最快的路：

# POCO 源码根目录（节选）：一个模块一个目录
Foundation/   # 地基模块
XML/          # XML 解析
JSON/         # JSON 解析与生成
Net/          # 网络与 HTTP
Util/         # 应用程序框架
Data/         # 数据库抽象层
  MySQL/      #    ├─ MySQL 连接器
  SQLite/     #    └─ SQLite 连接器
Crypto/       # 加密（需 OpenSSL）
NetSSL_OpenSSL/ # HTTPS（需 OpenSSL）

随手写个最小程序感受一下 Foundation 的日志能力——这是 POCO 里最简单的模块之一，一行代码就能往控制台输出带级别的日志。后面所有模块的代码风格都和它一致：类名带 Poco:: 前缀，头文件在 Poco/ 目录下：

// foundation_demo.cpp：体验 Foundation 的日志
#include <Poco/Logger.h>
#include <iostream>

int main() {
    Poco::Logger& logger = Poco::Logger::get("main");
    logger.information("POCO 就绪");   // 信息级日志
    logger.warning("这只是个演示");     // 警告级日志
    return 0;
}

11.3 源码编译：configure 参数逐项拆解

素材笔记记录了在 CentOS 上从源码编译 POCO 的真实全过程，我们按"下载 → 装依赖 → configure → make"四步走。第一步下载：POCO 托管在 GitHub，国内直连 clone 经常很慢，素材里的做法是先把仓库 fork 到 Gitee（码云）再 clone 加速——这是国内拉 GitHub 大仓库的通用技巧。第二步装依赖：编译至少需要 gcc-c++（C++ 编译器）和 make（构建工具），openssl-devel 是给 Crypto/NetSSL 模块准备的开发头文件：

# 第 1 步：下载源码（fork 到码云后 clone，加快下载速度）
git clone https://gitee.com/helioswei/poco.git
cd poco

# 第 2 步：编译环境准备（CentOS 用 yum）
yum install gcc-c++ make openssl-devel

第三步 configure 之前，有一个前置条件：POCO 从 1.10 版本起要求 C++14 编译器（GCC 5、Clang 3.4、Visual C++ 2015 起步），而素材环境的 CentOS 自带 GCC 是 4.8.5，不满足要求。所以笔记里明确写着"需要提前安装 GCC 5.1.0 来支持 C++14"——这正是第 3 章我们亲手从源码编译的那个 GCC！第 3 章的劳动在这里派上了用场：GCC 5.1 是第一个完整支持 C++14 的 GCC 版本，把它的 bin/ 加进 PATH 后，就可以开始配置了。素材里的 configure 命令是真实操作记录，逐项拆解如下：

# 第 3 步：configure——素材笔记里的真实命令（逐字保留）
./configure --shared --prefix=/usr/local/poco --cflags=-std=c++14 --include-path=/usr/include/mysql/ --library-path=/usr/lib64/mysql/ --omit=Data/ODBC,MongoDB,PDF

# 第 4 步：编译并安装（-j4 用 4 个核并行加速）
make -j4
make install

这里藏着一个关键知识点：POCO 的默认构建并不包含 Data/MySQL 连接器，因为连接器依赖 MySQL 官方客户端库，不是人人都有。configure 通过 --omit 参数指定"不编译哪些组件"，默认的 omit 清单里恰好排除了 Data/MySQL。素材命令把 omit 清单改写为只有 Data/ODBC,MongoDB,PDF 三项，等于把 Data/MySQL 从"被排除"名单里放了出来——再加上 --include-path 和 --library-path 给它指路，MySQL 连接器就能编译成功。这也解释了为什么素材里要先装 mysql-devel：没有 MySQL 的头文件和库，放出来也编不过。另外注意，configure 并没有"开启 MySQL"的专用开关；新版还提供了更专门的 --mysql-include= 和 --mysql-lib= 参数，作用和通用路径参数一样，只是更明确。

11.4 与 MySQL 集成：从 mysql-devel 到 Data/MySQL

现在把"接上 MySQL"这条链路完整走一遍。先回答一个朴素的问题：为什么编译 POCO 需要先装 mysql-devel？因为 POCO 的 Data/MySQL 连接器并不是自己从头实现 MySQL 协议，而是调用 MySQL 官方客户端库 libmysqlclient——编译连接器时需要 mysql.h 头文件（告诉编译器"有哪些函数可以调用"），链接时需要 libmysqlclient.so（告诉链接器"这些函数实现在哪"）。素材笔记的原话是："安装 mysql 时没有头文件，所以我们需要安装头文件"。mysql-devel 这个包就是专门提供开发用的头文件和库的，光装 mysql 服务端是不带的：

# 第 1 步：安装 MySQL 开发包（提供头文件和客户端库）
yum install mysql-devel

# 第 2 步：configure 时用路径参数给它"指路"（素材真实命令的关键片段）
./configure --include-path=/usr/include/mysql/ \
            --library-path=/usr/lib64/mysql/ \
            --omit=Data/ODBC,MongoDB,PDF

# 第 3 步：编译完成后，检查产物——应该能看到 MySQL 连接器库
make -j4
ls lib/ | grep -i mysql
# 输出示例：libPocoDataMySQL.so

链路的关键是顺序：先有 mysql-devel（原料），configure 才能指路（定位原料），make 才能产出 libPocoDataMySQL.so（成品）。如果漏装 mysql-devel，configure 本身不会报错，但 make 到 Data/MySQL 时会因为找不到 mysql.h 直接失败——这种"配置通过、编译失败"的现象，正是系统分析要抓的典型断点：问题不在编译，在更早的原料环节。

库编好了，代码里怎么用？三步：注册连接器 → 创建会话 → 执行 SQL。连接器要先通过 registerConnector() 告诉 Data 模块"我有 MySQL 这个连接类型"，然后 Poco::Data::Session 就能用连接串连上数据库。连接串是分号分隔的键值对，格式为 host=...;user=...;password=...;db=...：

// mysql_demo.cpp：连上 MySQL，插入一行再查出来
#include <Poco/Data/MySQL/Connector.h>
#include <Poco/Data/Session.h>
#include <Poco/Data/Statement.h>
#include <iostream>

int main() {
    // 第 1 步：注册 MySQL 连接器（必须，否则 Session 不认识 "MySQL"）
    Poco::Data::MySQL::Connector::registerConnector();

    // 第 2 步：创建会话，连接串格式 host/user/password/db
    Poco::Data::Session session("MySQL",
        "host=127.0.0.1;user=root;password=123456;db=test");

    // 第 3 步：执行 SQL——? 是占位符，use() 绑定参数，now 立即执行
    std::string name = "狄仁杰";
    session << "INSERT INTO users(name) VALUES(?)",
        Poco::Data::Keywords::use(name), Poco::Data::Keywords::now;

    // 查询：into() 把结果列装进变量，execute() 真正执行
    std::string got;
    Poco::Data::Statement select(session);
    select << "SELECT name FROM users", Poco::Data::Keywords::into(got);
    select.execute();
    std::cout << "查到的名字：" << got << std::endl;
    return 0;
}

11.5 现代集成方式：vcpkg 与 CMake

源码编译适合老环境、定制需求（比如必须用某个老 GCC、要改编译参数）；但对日常开发来说，第 5 章铺好的 vcpkg 才是省心之路。一条命令装好 POCO，连 MySQL 支持也只要在特性（feature）里点名。vcpkg 的 poco 端口把可选能力拆成了特性，mysql 特性会自动带上 Data 模块和 libmysql 依赖——注意 vcpkg 默认特性集并不包含 mysql，需要显式指定：

# 基础安装（Foundation/Net/JSON/XML/Util 等核心模块）
./vcpkg/vcpkg install poco

# 带上 MySQL 连接器（会自动拉取 libmysql 依赖）
./vcpkg/vcpkg install poco[mysql]

# 显式指定 64 位 Linux 平台
./vcpkg/vcpkg install poco[mysql]:x64-linux

装好之后，CMake 工程里用 find_package(Poco REQUIRED COMPONENTS ...) 按需声明要哪些模块，链接目标写作 Poco::模块名。vcpkg 安装时打印的提示里会列出它支持的组件名，照抄即可。下面这个 CMakeLists.txt 用到了 Foundation、Net、JSON 三个组件——正好对应 11.6 节第一个程序的需求：

# CMakeLists.txt：找到 POCO 并链接 Net/JSON/Foundation
cmake_minimum_required(VERSION 3.15)
project(poco_demo CXX)

find_package(Poco REQUIRED COMPONENTS Foundation Net JSON)
add_executable(poco_demo main.cpp)
target_link_libraries(poco_demo PRIVATE
    Poco::Foundation Poco::Net Poco::JSON)

如果走的是 11.3 节源码编译路线（装在 /usr/local/poco），CMake 找不到 Poco 时用 CMAKE_PREFIX_PATH 指一下安装目录；不用 CMake 的话，也可以直接用 g++ 手动链接。注意编译要加 -std=c++14（POCO 的要求），运行时还要让系统找到动态库：

# 源码编译路线：告诉 CMake POCO 装在哪
cmake -B build -DCMAKE_PREFIX_PATH=/usr/local/poco
cmake --build build

# 或者不用 CMake，g++ 手动链接（-lPocoNet 等按需取用）
g++ -std=c++14 main.cpp -I/usr/local/poco/include \
    -L/usr/local/poco/lib -lPocoNet -lPocoJSON -lPocoFoundation \
    -Wl,-rpath,/usr/local/poco/lib -o pocodemo
# -Wl,-rpath 把库路径写进程序，运行时不用手动设 LD_LIBRARY_PATH

11.6 第一个 POCO 程序：HTTP 客户端与 JSON 解析

万事俱备，写第一个真正干活的 POCO 程序。先呼应一下第 6 章：jsoncpp 里 JSON 文档是 Json::Value 树；POCO 里对应的是 Poco::JSON::Object::Ptr——智能指针管理的 JSON 对象，解析入口是 Poco::JSON::Parser。API 名字不同，但"文本 → 树 → 取值"的思路一模一样，第 6 章学的技能直接平移：

// json_demo.cpp：用 Poco::JSON 解析字符串（呼应第 6 章）
#include <Poco/JSON/Parser.h>
#include <Poco/JSON/Object.h>
#include <iostream>

int main() {
    std::string text =
        R"({"name":"狄仁杰","age":47,"skill":"系统分析"})";

    Poco::JSON::Parser parser;                          // 解析器
    Poco::Dynamic::Var result = parser.parse(text);  // 文本 → 动态值
    Poco::JSON::Object::Ptr obj =
        result.extract<Poco::JSON::Object::Ptr>();   // 转成 JSON 对象

    std::cout << obj->getValue<std::string>("name") << std::endl;  // 狄仁杰
    std::cout << obj->getValue<int>("age") << std::endl;         // 47
    return 0;
}

再把 11.1 节开头那个"劝退的手写 HTTP"用 POCO 重写一遍——这也是全章的收官程序：连服务器 → 发请求 → 收响应三步，各对应一个类。收到响应后，正文是一段 JSON，我们顺手用上面的 Poco::JSON 把它解析出来，Net 和 JSON 两个模块就这样第一次联手了：

// http_demo.cpp：HTTP GET + JSON 解析，Net 与 JSON 模块联手
#include <Poco/Net/HTTPClientSession.h>
#include <Poco/Net/HTTPRequest.h>
#include <Poco/Net/HTTPResponse.h>
#include <Poco/JSON/Parser.h>
#include <Poco/StreamCopier.h>
#include <iostream>

int main() {
    // 第 1 步：连上服务器（默认 80 端口）
    Poco::Net::HTTPClientSession session("httpbin.org");

    // 第 2 步：构造并发出 GET 请求
    Poco::Net::HTTPRequest req(Poco::Net::HTTPRequest::HTTP_GET,
        "/json", Poco::Net::HTTPMessage::HTTP_1_1);
    session.sendRequest(req);

    // 第 3 步：接收响应，打印状态码
    Poco::Net::HTTPResponse res;
    std::istream& body = session.receiveResponse(res);
    std::cout << res.getStatus() << " " << res.getReason() << std::endl;

    // 响应正文整个拷进字符串，再用 Poco::JSON 解析
    std::string text;
    Poco::StreamCopier::copyToString(body, text);
    Poco::JSON::Parser parser;
    Poco::Dynamic::Var v = parser.parse(text);
    std::cout << "响应体开头： " << text.substr(0, 60) << "..." << std::endl;
    return 0;
}

Poco::JSON::Parser parser;
Poco::Dynamic::Var v = parser.parse(
    R"({"server":{"host":"127.0.0.1","port":8080}})");
Poco::JSON::Object::Ptr root = v.extract<Poco::JSON::Object::Ptr>();
Poco::JSON::Object::Ptr server = root->getObject("server");
if (server) {
    std::cout << server->getValue<int>("port") << std::endl;  // 8080
}