# 项目结构

## 组织理念

按功能域/关注点分包的扁平结构。每个顶级目录是一个独立的 Go 包，负责一个明确的职责域。不采用深层嵌套，保持单层包结构为主。

## 目录设计模式

### 核心功能包
**路径**: `/containers/`, `/node/`, `/ebpftracer/`, `/tracing/`  
**目的**: 各采集域的核心逻辑  
**模式**: 一个包对应一个监控维度（容器、节点、eBPF追踪、APM追踪）

### 基础设施包
**路径**: `/common/`, `/config/`, `/flags/`, `/proc/`, `/utils/`  
**目的**: 跨包共享的基础能力（网络、配置、进程文件系统、工具函数）  
**模式**: 无业务逻辑，纯工具性质

### 内核子系统包
**路径**: `/cgroup/`, `/pinger/`, `/logs/`  
**目的**: 与特定 Linux 子系统交互  
**模式**: 封装系统调用和文件解析细节

### eBPF 子包
**路径**: `/ebpftracer/ebpf/`, `/ebpftracer/l7/`, `/ebpftracer/tracer/`  
**目的**: eBPF 程序源码（C）、L7 协议解析、tracer 类型定义  
**模式**: `ebpftracer/` 是唯一有子包的功能包

### 外部集成
**路径**: `/kube/`, `/prom/`, `/profiling/`  
**目的**: Kubernetes 客户端、Prometheus 代理指标、性能分析  
**模式**: 对外部系统的薄封装层

## 命名规范

- **文件**: snake_case（`container_apm.go`, `tail_reader.go`）
- **Go 包**: 小写单词（`ebpftracer`, `containers`）
- **前缀分组**: 同域文件使用共同前缀（`apm_heartbeat.go`, `apm_register_app.go`, `apm_white_list.go`）
- **平台文件**: `_linux.go` / `_linux_amd64.go` / `_linux_arm64.go` 后缀区分平台
- **测试文件**: `*_test.go` 与源文件同目录

## 导入组织

```go
import (
    // 标准库
    "fmt"
    "os"

    // 项目内部包
    "github.com/coroot/coroot-node-agent/common"
    "github.com/coroot/coroot-node-agent/flags"
    . "github.com/coroot/coroot-node-agent/utils/modelse"

    // 第三方库
    "github.com/cilium/ebpf"
    klog "github.com/sirupsen/logrus"
)
```

**模式**:
- 标准库 → 内部包 → 第三方（三段式）
- `klog` 作为 logrus 的标准别名
- 点导入仅用于 `utils/modelse`（模型/类型定义）

## 代码组织原则

- **APM 功能集中**: 所有 APM 相关逻辑放在 `containers/apm_*.go` 文件中
- **入口统一**: `main.go` 负责初始化、信号处理和 HTTP 服务启动
- **fixtures 模式**: 测试数据放在对应包的 `fixtures/` 子目录
- **构建产物**: 输出到 `dist/<arch>/package_dir/bin/euspace`
- **容器镜像**: 基于自定义 base 镜像 `harbor.cloudwise.com/apm/euspace-base`

---
_本规范聚焦设计模式而非具体文件树结构。遵循本模式新增文件时，无需更新此文档_
