# 目录规范

> 此开源图书由[ithaiq](https://github.com/ithaiq)原创，创作不易转载请注明出处

*   推荐

    考虑先包含 cmd、pkg、internal 3 个目录
* /web 前端代码存放目录，主要用来存放Web静态资源，服务端模板和单页应用（SPAs）
* /cmd 统一main 函数
* /internal 存放**私有应用**和库代码。如果一些代码，你不希望在其他应用和库中被导入
  * /internal/pkg：内部共享包存放的目录
    * /internal/pkg/code：项目业务 Code 码。
    * /internal/pkg/validation：一些通用的验证函数。
    * /internal/pkg/middleware：HTTP 处理链。
  * /internal/apiserver
    * /internal/apiserver/api/v1：HTTP API 接口的具体实现，主要用来做 HTTP 请求的解包、参数校验、业务逻辑处理、返回。注意这里的业务逻辑处理应该是轻量级的，如果业务逻辑比较复杂，代码量比较多，建议放到 /internal/apiserver/service 目录下。该源码文件主要用来串流程。
    * /internal/apiserver/options：应用的 command flag。
    * /internal/apiserver/config：根据命令行参数创建应用配置。
    * /internal/apiserver/service：存放应用复杂业务处理代码。
    * /internal/apiserver/store/mysql：一个应用可能要持久化的存储一些数据，这里主要存放跟数据库交互的代码，比如 Create、Update、Delete、Get、List 等。
* /pkg 可以被外部应用使用的代码库
* /vendor go mod vendor 创建
* /third\_party Swagger UI fork库
* /test 存放其他外部测试应用和测试数据
* /configs 配置 不能携带敏感信息 用占位符来替代如`${CONFIG_USER_USERNAME}`
* /deployments k8s yaml
* /init 存放初始化系统（systemd，upstart，sysv）和进程管理配置文件（runit，supervisord）。比如 sysemd 的 unit 文件。这类文件，在非容器化部署的项目中会用到
* /Makefile gen -> format -> lint -> test -> build
* /scripts 存放脚本文件，实现构建、安装、分析等不同功能
  * /scripts/make-rules：用来存放 makefile 文件，实现/Makefile 文件中的各个功能
  * /scripts/lib：shell 库，用来存放 shell 脚本
    * shell 脚本中的函数名，建议采用语义化的命名方式，例如 `iam::log::info` 这种语义化的命名方式
  * /scripts/install：如果项目支持自动化部署
* /build 这里存放安装包和持续集成相关的文件
  * /build/ci
  * /build/docker
  * /build/package：存放容器（Docker）、系统（deb, rpm, pkg）的包配置和脚本
* /tools 存放这个项目的支持工具。这些工具可导入来自/pkg 和/internal 目录的代码。
* /githooks git钩子 我们可以将 commit-msg 存放在该目录
* /assets 项目使用的其他资源(图片、CSS、JavaScript 等)。
* /website 项目网站相关的数据
* /README.md 借助工具 [tocenize](https://github.com/nochso/tocenize) 来完成索引的添加。
* /docs
* /CONTRIBUTING.md 开源项目如何贡献代码，如何开源协同
* /api 目录中存放的是当前项目对外提供的各种不同类型的 API 接口定义文件
* /LICENSE 版权
  * 为了声明版权，你可能会需要将 LICENSE 头添加到源码文件或者其他文件中，这部分工作可以通过工具实现自动化，推荐工具： [addlicense](https://github.com/marmotedu/addlicense)
  * 需要知道代码引用了哪些源码，以及这些源码的开源协议，可以借助工具来进行检查，推荐工具： [glice](https://github.com/ribice/glice) 。至于如何说明对其它源码的引用，大家可以参考下 IAM 项目的 [LICENSE](https://github.com/marmotedu/iam/blob/master/LICENSE) 文件
* /CHANGELOG 我们可以结合 [Angular规范](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines) 和 [git-chglog](https://github.com/git-chglog/git-chglog) 来自动生成 CHANGELOG
* /examples 示例代码快速上手
* 其他
  * 空目录下加一个 `.keep` 文件
