传统做法（混乱）                  Bazel 做法（清晰）────────────────────────────    ─────────────────────────全局头文件                          声明式依赖#include<vector>                   #include<vector>#include"mylib.h"                  #include"mylib.h"// mylib.h 必须在 hdrs 中声明                                  // 或通过 deps 引用隐式依赖                           显式依赖编译器自行查找                      Bazel 确保所有依赖都被声明                                   -> 减少编译时 surprises

// 1. 公共头文件（通过 hdrs 声明）—— 对外暴露 API// mylib.h#pragma oncevoidpublic_function();  // 其他包可以通过 deps 引用此库后使用// 2. 私有头文件（仅在 srcs 中）—— 内部实现// mylib_internal.hvoidinternal_function();  // 只在 mylib.cc 中使用// 3. 内联头文件（不声明）—— 仅 include 的实现// inline_math.hinline intadd(int a, int b) { return a + b; }  // 仅在 .cc 中包含

cc_library(    name = "my_lib",    srcs = ["mylib.cc"],    hdrs = ["mylib.h"],    includes = ["include"],  # 添加 include 目录到编译器包含路径)

// mylib.cc#include"other.h"  #include 在 include 目录中查找

编译器查找顺序：1. 源文件所在目录（srcs 所在目录）2. includes 指定的目录3. 依赖目标的 includes（按依赖顺序）4. 系统头文件（<>）

# ✅ 推荐做法cc_library(    name = "json_parser",    hdrs = ["json_parser.h"],    srcs = ["json_parser.cc"],    includes = ["include"],  # 将 include 目录作为根目录)# 使用时// json_parser.cc#include"json_parser.h"          # 在 include/json_parser.h 中查找#include"third_party/json.h"     # 在依赖 includes 中查找

# ❌ 不推荐：硬编码绝对路径# 会破坏 Bazel 的依赖管理cc_library(    name = "bad_lib",    copts = ["-I/path/to/includes"],  # 避免！)

cc_library(    name = "api",    srcs = ["api.cc"],           # 当前目标使用的实现文件    hdrs = ["api.h"],           # 公共 API，其他包可以通过 #include 使用    deps = [        "//core:types",        # 当前目标的依赖        "//third_party:json",    ],)# 其他包中使用cc_library(    name = "user",    srcs = ["user.cc"],    deps = ["//api"],           # 可以 #include "api.h")

hdrs 传播给依赖者 ✅  ——  user.cc 可以 #include"api.h"srcs 不传播 ❌       ——  user.cc 不能 #include"api.cc"deps 传播给依赖者 ✅  ——  user 可以依赖 api 的依赖（如 json）

# ❌ 暴露了过多内部细节cc_library(    name = "public_api",    hdrs = ["api.h", "internal_impl.h", "config.h"],  # internal_impl.h 不该暴露    srcs = ["api.cc"],)# ✅ 只暴露必要的 APIcc_library(    name = "public_api",    hdrs = ["api.h"],           # 只包含公共接口    srcs = ["api.cc", "internal_impl.h"],  # 实现细节放在 srcs)

// src/pch.h#pragma once// 常用标准库头文件#include<memory>#include<string>#include<vector>#include<map>#include<unordered_map>#include<algorithm>#include<iostream>// 项目常用头文件#include"base/types.h"#include"base/logging.h"

# src/BUILD# 预编译头库cc_library(    name = "pch",    srcs = ["pch.cc"],  # 必须提供一个源文件    hdrs = ["pch.h"],)# 使用 PCH 的库cc_library(    name = "utils",    srcs = ["utils.cc"],    hdrs = ["utils.h"],    deps = [":pch"],    # Bazel 会自动处理 PCH)

# .bazelrcbuild --copt=/Yc"pch.h"     # 生成 PCHbuild --copt=/Yu"pch.h"     # 使用 PCH# BUILD 文件cc_library(    name = "windows_utils",    srcs = ["utils.cc"],    hdrs = ["utils.h"],    deps = [":pch"],)

cc_library(    name = "platform_lib",    srcs = ["platform_lib.cc"],    hdrs = select({        "//:windows": ["windows_platform.h"],        "//:linux": ["linux_platform.h"],        "//conditions:default": ["default_platform.h"],    }),    deps = select({        "//:windows": ["//third_party:windows_api"],        "//:linux": ["//third_party:linux_api"],        "//conditions:default": [],    }),)

platform/├── BUILD├── common.h               # 平台无关的部分├── windows/│   ├── platform.h│   └── windows_impl.h├── linux/│   ├── platform.h│   └── linux_impl.h└── macos/    ├── platform.h    └── macos_impl.h

# platform/BUILDpackage(default_visibility = ["//visibility:public"])# 公共接口cc_library(    name = "common",    hdrs = ["common.h"],)# Windows 平台实现cc_library(    name = "windows_impl",    srcs = glob(["windows/*.cc"]),    hdrs = ["windows/platform.h"],    deps = [        ":common",        "//third_party:windows_api",    ],    visibility = ["//visibility:private"],  # 不直接暴露)# 平台库别名alias(    name = "platform",    actual = select({        "//:windows": ":windows_impl",        "//:linux": ":linux_impl",        "//:macos": ":macos_impl",        "//conditions:default": ":common",    }),)

// 推荐的包含顺序// 1. 相关的头文件（防止编译依赖）#include"parser.h"#include"evaluator.h"// 2. C 标准库#include<cstdio>#include<cstring>// 3. C++ 标准库#include<vector>#include<string>// 4. 第三方库#include<absl/strings/str_split.h>#include<json/json.h>// 5. 本项目其他头文件#include"base/types.h"#include"base/logging.h"

// ✅ 使用现代 C++ 防护#pragma once// 或#ifndef MYLIB_H_#define MYLIB_H_...#endif// MYLIB_H_// ❌ 避免：使用宏定义包含文件#ifdef __cplusplusextern "C" {#endif#include"some_c_header.h"#ifdef __cplusplus}#endif

// ✅ 优先使用前向声明classDatabaseConnection;  // 前向声明classLogger;classUserService{ public:  void ProcessRequest(const std::string& request); private:  std::unique_ptr<DatabaseConnection> db_;  std::shared_ptr<Logger> logger_;};// ✅ 只有真正需要类型定义时才包含#include "database_connection.h"  // 需要 DatabaseConnection::Impl

# 查看编译命令bazel build //src:my_lib --verbose_executables# 查看预处理后的文件bazel build //src:my_lib --action_env=VERBOSE=1# 查看依赖图bazel query "deps(//src:my_lib)" --output=label# 查看包含路径bazel build //src:my_lib --subcommands | grep "cc"

# 查看实际的编译选项bazel cquery "cc_library(//src:my_lib)" --output=build# 查看详细的配置信息bazel cquery "cc_library(//src:my_lib)" --output=starlark

// utils/string_utils.h#pragma once#include<string>#include<vector>#include<span>namespace utils {// 接口分离class StringProcessor { public:  virtual ~StringProcessor() = default;  virtual std::string Process(const std::string& input)= 0;};// 实现分离class DefaultStringProcessor : public StringProcessor { public:  std::string Process(const std::string& input)override;};// 工具函数std::vector<std::string> Split(const std::string& s, char delim);std::string Join(const std::vector<std::string>& v, std::string_view delim);}  // namespace utils

# 每个头文件一个目标，减少编译依赖# string_utils/BUILDcc_library(    name = "string_types",    hdrs = ["string_types.h"],)cc_library(    name = "string_processor",    srcs = ["string_processor.cc"],    hdrs = ["string_processor.h"],    deps = [":string_types"],)cc_library(    name = "string_utils",    srcs = ["string_utils.cc"],    hdrs = ["string_utils.h"],    deps = [":string_processor"],)

# API 声明与实现分离cc_library(    name = "api_interface",    hdrs = ["api.h"],    # 只有接口，没有实现    visibility = ["//visibility:public"],)cc_library(    name = "api_impl",    srcs = ["api.cc"],    deps = [":api_interface"],    visibility = ["//visibility:private"],  # 实现细节隐藏)# 使用者只依赖接口cc_binary(    name = "app",    deps = [":api_interface"],)

// ❌ 头文件依赖过多#include<vector>#include<map>#include<string>#include<algorithm>#include<memory>#include<thread>#include<mutex>#include<condition_variable>// ✅ 使用前向声明#include<memory>class DatabaseConnection;class Logger;class CacheManager;

// ❌ 依赖复杂类型时使用前向声明导致实现分散classDatabaseService{ private:  classImpl;  // 前向声明  std::unique_ptr<Impl> pimpl_;};// ✅ 在头文件中包含，在源文件中实现classDatabaseService{ public:  explicit DatabaseService(const Config& config); private:  Impl impl_;  // 直接包含实现类};

cc_library(    name = "public_api",    hdrs = ["api.h"],    srcs = ["api.cc"],    deps = [        "//base:types",            # 公共依赖，传播给使用者    ],    implementation_deps = [        "//core:heavy_dependency", # 实现依赖，不传播        "//third_party:expensive",    ],)# 使用者编译更快，不会因为内部实现变化而重新编译