# 后端目录结构

> Go 后端工程的目录职责与代码组织约定。

## 目录职责

```text
oci-portal/
├── go.mod              模块名 oci-portal,依赖 oracle/oci-go-sdk/v65
├── go.sum
├── cmd/
│   └── server/         启动入口 main.go
└── internal/
    ├── api/            HTTP 路由、参数绑定、响应、中间件
    ├── config/         环境变量读取
    ├── crypto/         敏感字段 AES-GCM 加解密
    ├── database/       SQLite 连接和 AutoMigrate
    ├── model/          GORM 数据模型
    ├── oci/            OCI SDK 封装,真实云请求只出现在此包
    └── service/        业务逻辑和本地快照同步
```

已实现:API Key 导入(ini 原文或显式字段)、测活(Identity GetTenancy)、账户类别判定(Organizations CLOUDCM 订阅)、重新测活时的快照差异同步。

## 代码组织约定

- 布局遵循官方约定:入口在 `cmd/<binary>/main.go`,非导出实现放 `internal/`(出现对外复用库时才建 `pkg/`),不过度分层。
- 接口定义在使用方包中;先有第二个实现或测试替身需求,再抽接口。
- 用 guard clause 尽早 return,减少嵌套。
- `defer` 紧跟资源获取语句,成对管理释放。
- 结构体初始化写字段名;已知容量的 slice/map 用 `make(T, 0, n)` 预分配。
- 注释解释"为什么"而非"是什么";导出符号写以名字开头的 godoc 注释。