红旗信号与设计原则

class TokenBucket {              // 只是把几个字段包了一层
public:
    double tokens() const;
    void   setTokens(double t);
    double ratePerSec() const;
    Clock::time_point lastRefill() const;
    void   setLastRefill(Clock::time_point t);
};

// 每个调用点都要重复这套算法：
auto now = Clock::now();
double t = b.tokens() + b.ratePerSec() * secondsBetween(b.lastRefill(), now);
b.setTokens(std::min(t, kBurst));  b.setLastRefill(now);
if (b.tokens() >= 1) { b.setTokens(b.tokens() - 1); handle(req); }

// 令牌桶限流器：每秒补充 ratePerSec 个令牌，最多攒 burst 个。线程安全。
class RateLimiter {
public:
    RateLimiter(double ratePerSec, double burst);
    // 有令牌就扣掉一个并返回 true；否则立即返回 false（不阻塞）。
    bool tryAcquire();
};

if (limiter.tryAcquire()) handle(req);
else reply429(req);

补充算法、时钟、并发保护都藏进了类里，调用者只需要知道一个方法。

// audit_writer.cpp
void AuditWriter::append(const Event& e) {
    out_ << e.ts << '|' << e.user << '|' << e.action << '\n';
}

// audit_report.cpp（另一个人写的）
Event parseLine(const std::string& line) {
    auto f = split(line, '|');       // 也得知道分隔符和字段顺序
    return Event{std::stoll(f[0]), f[1], f[2]};
}
// action 里哪天出现了 '|'，或者要加一个字段：两边都得改

// 审计日志。磁盘上的格式（分隔、转义、字段顺序、版本）只有这个类知道。
class AuditLog {
public:
    explicit AuditLog(const std::string& path);
    void append(const Event& e);
    // 按写入顺序回放每条事件；损坏的行跳过，并计入 corruptLines()。
    void forEach(const std::function<void(const Event&)>& fn) const;
    size_t corruptLines() const;
};
// 报表模块只和 Event 打交道

class FetchStep {     // 第 1 步：拉取远端变更
    // 要懂：URL 拼法、鉴权头、分页游标、JSON 字段名
    std::vector<Record> run(const std::string& sinceCursor);
};
class MergeStep {     // 第 2 步：和本地数据合并
    std::vector<Record> run(std::vector<Record> remote, LocalDb& db);
};
class UploadStep {    // 第 3 步：推送本地变更
    // 又要懂：URL 拼法、鉴权头、JSON 字段名、每批最多 500 条
    void run(const std::vector<Record>& changes);
};

// 远端存储：协议细节（URL、鉴权、分页、批量上限、JSON）全在这里。
class RemoteStore {
public:
    std::vector<Record> changesSince(Cursor& cursor);  // 内部自动翻页
    void push(const std::vector<Record>& changes);      // 内部自动分批
};

// 顺序仍然存在，只是变成了一个函数里的三行
void sync(RemoteStore& remote, LocalDb& db) {
    auto incoming = remote.changesSince(db.cursor());
    auto outgoing = db.merge(incoming);
    remote.push(outgoing);
}

auto log = Logger::create(
    "app.log",
    /*maxBytes=*/64 << 20,
    /*maxFiles=*/5,
    /*flushEveryN=*/1,
    /*async=*/false,
    /*queueCapacity=*/0,
    Encoding::Utf8);
log.write(Level::Info, "server started", /*tags=*/{});

// 默认：按 64 MB 轮转、保留 5 份、同步写。大多数程序只需要这两行。
auto log = Logger::open("app.log");
log.info("server started");

// 少数人才需要的调优，放进单独的选项结构
LoggerOptions opt;
opt.async = true;
opt.queueCapacity = 1 << 16;
auto trace = Logger::open("trace.log", opt);

class UserService {
public:
    std::optional<User> findById(UserId id) { return repo_.findById(id); }
    std::vector<User> findByEmail(const std::string& e) { return repo_.findByEmail(e); }
    void save(const User& u) { repo_.save(u); }
    void remove(UserId id)   { repo_.remove(id); }
    // ……还有 9 个，长得都一样
private:
    UserRepository repo_;
};

// 没有额外价值时：调用者直接用 UserRepository，删掉这一层。
// 需要这一层时：让它承担存储层不该管的事，接口自然就不同了。
class AccountService {
public:
    // 注册：校验邮箱格式与唯一性、哈希密码、写库、发欢迎邮件。
    // 邮箱已被占用时返回 RegisterError::EmailTaken。
    Result<UserId, RegisterError> registerUser(const SignupForm& form);
    // 注销：删除用户并吊销其全部会话；用户不存在时什么也不做。
    void closeAccount(UserId id);
};

for (int i = 0; i < 3; ++i) {                       // 拉取配置
    if (auto r = http.get(cfgUrl); r.ok()) { cfg = r.body(); break; }
    std::this_thread::sleep_for(100ms * (1 << i));
}
for (int i = 0; i < 3; ++i) {                       // 上报指标
    if (http.post(metricsUrl, m).ok()) break;
    std::this_thread::sleep_for(100ms * (1 << i));
}
// 下单、发通知……又各抄一遍；其中一份写成了 10ms * i

// 反复调用 op，直到它返回 true 或已试满 attempts 次；两次之间按指数退避
// （100ms、200ms、400ms……）。返回最后一次 op 的结果。
bool retryWithBackoff(int attempts, const std::function<bool()>& op);

retryWithBackoff(3, [&] {
    auto r = http.get(cfgUrl);
    if (r.ok()) cfg = r.body();
    return r.ok();
});
retryWithBackoff(3, [&] { return http.post(metricsUrl, m).ok(); });

template <class K, class V>
class LruCache {
public:
    void put(const K& key, V value) {
        if constexpr (std::is_same_v<V, Thumbnail>) {   // 缩略图特判
            if (value.width > 2048) return;              // 太大的不缓存
            metrics::thumbnailsCached.inc();
        }
        insertFront(key, std::move(value));
        if (size_ > capacity_) evictOldest();
    }
};

template <class K, class V>
class LruCache {            // 通用：满了就淘汰最久没被访问的条目
public:
    void put(const K& key, V value);
    std::optional<V> get(const K& key);
};
class ThumbnailStore {      // 专用：缩略图的规矩放在缩略图模块
    LruCache<std::string, Thumbnail> cache_;
public:
    void remember(const std::string& url, Thumbnail t) {
        if (t.width > kMaxCachedWidth) return;
        cache_.put(url, std::move(t));
        metrics::thumbnailsCached.inc();
    }
};

// 前置条件：先调用 prepareRow()
void Importer::prepareRow(const std::string& line) {
    fields_ = split(line, ',');
    if (fields_.size() == 3)                      // 旧格式没有 region 列
        fields_.insert(fields_.begin() + 2, "");
    pos_ = 0;
}
Order Importer::buildOrder() {
    Order o;
    o.id     = fields_[pos_++];
    o.user   = fields_[pos_++];
    o.region = fields_[pos_++];   // 为什么会是空串？得回去看 prepareRow
    o.amount = parseAmount(fields_[pos_++]);
    return o;
}

// 把一行 CSV 解析成订单。新格式 4 列：id,user,region,amount；
// 也接受旧格式 3 列（没有 region，此时 region 为空串）。
// 列数不对或金额不是数字时抛 ImportError，消息里带原始行。
Order parseOrderLine(const std::string& line) {
    auto f = split(line, ',');
    if (f.size() == 3) f.insert(f.begin() + 2, "");
    if (f.size() != 4) throw ImportError("bad column count: " + line);
    return Order{f[0], f[1], f[2], parseAmount(f[3])};
}

class ConnPool {
    int maxIdle_;                        // 最大空闲数
    std::chrono::seconds idleTimeout_;   // 空闲超时

    // 获取连接
    Conn acquire();
    // 归还连接
    void release(Conn c);
};

class ConnPool {
    // 归还时若空闲连接已达此数，直接关闭归还的连接；0 表示不保留空闲连接。
    int maxIdle_;
    // 空闲超过此时长的连接，会在下次 acquire 时被关闭而不是交出去，
    // 以免调用者拿到已被服务端断开的连接。
    std::chrono::seconds idleTimeout_;

    // 返回一个可用连接：优先复用空闲连接，否则新建。活跃连接数已达上限时
    // 阻塞等待，最多等 acquireTimeout_，超时抛 PoolExhausted。
    Conn acquire();
    // 把 c 交还给池。c 之后不得再使用；归还已断开的连接是安全的。
    void release(Conn c);
};

// 内部用 unordered_map<string, list::iterator> 加一条双向链表维护
// 访问顺序。get 时把节点 splice 到表头；put 超容量时从表尾 pop_back。
// mu_ 保护上述两个结构。返回 key 对应的值。
std::optional<std::string> get(const std::string& key);

// 返回 key 当前缓存的值；不存在（从未写入或已被淘汰）时返回 nullopt。
// 命中会让该条目成为"最近使用"，因而最晚被淘汰。线程安全，O(1)。
std::optional<std::string> get(const std::string& key);

// 链表与 splice 的说明放进 .cpp 里函数体内的实现注释。

struct Session {
    int64_t     time;     // 创建时间？最后活跃？过期时刻？秒还是毫秒？
    bool        flag;
    int         count;
    std::string data;
};
void process(Session& s);

if (s.flag && now - s.time > limit) process(s);

struct Session {
    int64_t     lastActiveMs;    // 最后一次收到请求的时刻，Unix 毫秒
    bool        loggedIn;
    int         failedLogins;    // 连续登录失败次数，成功后清零
    std::string csrfToken;
};
void expire(Session& s);

if (s.loggedIn && nowMs - s.lastActiveMs > idleLimitMs) expire(s);

// 该叫什么？pending？sendState？offsetOrStatus？……
// -1：还没连上；0：连上了但还没发数据；>0：已发送的字节数
int64_t sendInfo = -1;

void onConnected()    { sendInfo = 0; }
void onSent(size_t n) { sendInfo += n; }
bool canSend() const  { return sendInfo >= 0; }

bool     connected = false;
uint64_t bytesSent = 0;      // 本连接累计发送的字节数

void onConnected()    { connected = true; }
void onSent(size_t n) { bytesSent += n; }
bool canSend() const  { return connected; }

// 把 buf 写入 path。append 为 true 时追加，否则覆盖；但 atomic 为 true 时
// 忽略 append，改为先写临时文件再 rename。fsync 为 true 时写完刷盘，但在
// atomic 模式下刷的是临时文件，rename 后目录项不刷。返回值：>=0 为写入
// 字节数；-1 打开失败（看 errno）；-2 部分写入，文件可能处于半写状态
// （atomic 模式下不会出现 -2）。
int writeFile(const std::string& path, std::string_view buf,
              bool append, bool atomic, bool fsync);

// 用 data 原子地替换 path 的全部内容：要么完整写入新内容，要么保留旧内容，
// 崩溃或断电后不会出现半个文件。失败时抛 IoError。
void replaceFileAtomically(const std::string& path, std::string_view data);

// 把 data 追加到 path 末尾，文件不存在则创建。失败时抛 IoError。
void appendToFile(const std::string& path, std::string_view data);

schedule(job, 3, true, false);          // 3？true？false？
if ((job.state & 0x4) && !(job.state & 0x10))
    retry(job);

// 看起来只是读一下长度
size_t n = queue.size();   // 实际上会先把缓冲的批次刷到磁盘

schedule(job, Priority::High, Placement::AnyWorker, Retry::Never);
if (job.failed() && !job.cancelled())
    retry(job);

// 有副作用的操作在名字上说出来；查询就只查询
queue.flushPending();
size_t n = queue.size();