目录

项目开发维护 | 文档规范

1. 文档规范

文档是项目中很重要的组成部分,没有文档的项目很难理解、部署和使用。因此,编写文档是一个必不可少的开发工作。一个项目中最需要的 3 类文档是 README 文档、项目文档和 API 接口文档。

1.1. README 文档

README 文档是项目的门面,它是开发者学习项目时第一个阅读的文档,会放在项目的根目录下。它主要用来介绍项目的功能、安装、部署和使用

READM 规范中的内容如下所示。有一个在线的 README 生成工具,叫做 readme.so 可以参考下。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

# 项目名称

<!-- 写一段简短的话描述项目 -->

## 功能特性

<!-- 描述该项目的核心功能点 -->

## 软件架构(可选)

<!-- 可以描述下项目的架构 -->

## 快速开始

### 依赖检查

<!-- 描述该项目的依赖,比如依赖的包、工具或者其他任何依赖项 -->

### 构建

<!-- 描述如何构建该项目 -->

### 运行

<!-- 描述如何运行该项目 -->

## 使用指南

<!-- 描述如何使用该项目 -->

## 如何贡献

<!-- 告诉其他开发者如果给该项目贡献源码 -->

## 社区(可选)

<!-- 如果有需要可以介绍一些社区相关的内容 -->

## 关于作者

<!-- 这里写上项目作者 -->

## 谁在用(可选)

<!-- 可以列出使用本项目的其他有影响力的项目,算是给项目打个广告吧 -->

## 许可证

<!-- 这里链接上该项目的开源许可证 -->

一个实际的例子如下所示:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
# IAM - 身份识别与访问管理系统

IAM = Identity and Access Management

IAM 是一个基于 Go 语言开发的身份识别与访问管理系统,用于对资源访问进行授权。同时也具有如下能力:

1. 配合极客时间专栏 **《[Go 语言项目开发实战](https://time.geekbang.org/column/intro/100079601)》**,讲解如何用 Go 做企业级应用的开发,是该项目的理论课程,包含了项目各个知识点和构建思路的讲解,也会包含我的一线研发经验和建议。

   目录请参考:[《Go 语言项目开发实战》课程目录](./docs/guide/zh-CN/geekbang/geekbang_course_catalog.md)


2. 作为一个开发脚手架,供开发者克隆后二次开发,快速构建自己的应用。

IAM 项目会长期维护、定期更新,**欢迎兄弟们 Star & Contributing**

## 功能特性

本项目用到了Go企业开发的大部分核心技能点,见下图:

![技术思维导图](./docs/images/技术思维导图.png)

更多请参考:[marmotedu/gocollect](https://github.com/marmotedu/gocollect)

## 软件架构

![IAM架构](./docs/images/IAM架构.png)

架构解析见:[IAM 架构 & 能力说明](docs/guide/zh-CN/installation/installation-architecture.md)

## 快速开始

### 依赖检查

**Minimum Requirements**

- Hardware
  - 2 GB of Memory
  - 50 GB of Disk Space
- 操作系统:CentOS Linux 8.2 (64-bit)
- 正常访问外网

 **需求检查 & 依赖安装** 

 请参考:[](docs/guide/zh-CN/installation/installation-requirement.md)

### 构建

1. 代码包下载

​```
$ git clone https://github.com/marmotedu/iam
​```

2. 编译

​```bash
$ cd iam
$ make
​```

### 运行

​```bash
./scripts/install/install.sh iam::install::install_iam    
​```

## 使用指南

[IAM Documentation](docs/guide/zh-CN)

## 如何贡献

欢迎贡献代码,贡献流程可以参考 [developer's documentation](docs/devel/zh-CN/development.md)。

## 社区

You are encouraged to communicate most things via [GitHub issues](https://github.com/marmotedu/iam/issues/new/choose) or pull requests.

## 关于作者

- Lingfei Kong <colin404@foxmail.com>

为了方便交流,我建了微信群,可以加我 **微信:nightskong**,拉你入群,方便交流。

## 谁在用

如果你有项目在使用iam系统模板,也欢迎联系作者,加入使用案例。

## 许可证

IAM is licensed under the MIT. See [LICENSE](LICENSE) for the full license text.

1.2. 项目文档

项目文档包括了一切需要文档化的内容,通常集中放在 /docs 目录下。好的文档规范有两个优点:易读和可以快速定位文档。不同项目有不同的文档需求,但是一般都会考虑以下两类文档:

  • 开发文档:用来说明该项目的开发流程,比如如何搭建开发环境、构建二进制文件、测试、部署等。
  • 用户文档:软件的使用文档,对象一般是软件的使用者,内容可根据需要添加。比如,可以包含 API 文档、SDK 文档、安装文档、功能介绍文档、最佳实践、操作指南、常见问题等。

为了方便全球开发者和用户使用,开发文档和用户文档,可以预先规划好英文和中文两个版本。

下面是一个项目文档的示例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

docs
├── devel                            # 开发文档,可以提前规划好,英文版文档和中文版文档
│   ├── en-US/                       # 英文版文档,可以根据需要组织文件结构
│   └── zh-CN                        # 中文版文档,可以根据需要组织文件结构
│       └── development.md           # 开发手册,可以说明如何编译、构建、运行项目
├── guide                            # 用户文档
│   ├── en-US/                       # 英文版文档,可以根据需要组织文件结构
│   └── zh-CN                        # 中文版文档,可以根据需要组织文件结构
│       ├── api/                     # API文档
│       ├── best-practice            # 最佳实践,存放一些比较重要的实践文章
│       │   └── authorization.md
│       ├── faq                      # 常见问题
│       │   ├── iam-apiserver
│       │   └── installation
│       ├── installation             # 安装文档
│       │   └── installation.md
│       ├── introduction/            # 产品介绍文档
│       ├── operation-guide          # 操作指南,里面可以根据RESTful资源再划分为更细的子目录,用来存放系统核心/全部功能的操作手册
│       │   ├── policy.md
│       │   ├── secret.md
│       │   └── user.md
│       ├── quickstart               # 快速入门
│       │   └── quickstart.md
│       ├── README.md                # 用户文档入口文件
│       └── sdk                      # SDK文档
│           └── golang.md
└── images                           # 图片存放目录
    └── 部署架构v1.png

1.3. API 文档

接口文档又称为 API 文档,一般由后台开发人员编写,用来描述组件提供的 API 接口,以及如何调用这些 API 接口。

在项目初期,接口文档可以解耦前后端,前后端并行开发:前端只需要按照接口文档实现调用逻辑,后端只需要按照接口文档提供功能。

当前后端都开发完成之后,我们就可以直接进行联调,提高开发效率。在项目后期,API 文档可以提供给使用者,不仅可以降低组件的使用门槛,还能够减少沟通成本。

1.3.1. API 文档编写方式

API 文档有四种编写方式,包括编写 word 格式文档、借助工具编写、通过注释生成和编写 Markdown 格式文档。具体实现如下所示:

https://img.dawnguo.cn/dev/912fe30a70df0866d168ef1c0a50cb63.jpeg其中,通过注释生成和编写 Markdown 格式文档这 2 种方式用得最多。推荐使用 Markdown 格式文档的方式,原因如下:

  • 相比通过注释生成的方式,编写 Markdown 格式的接口文档,能表达更丰富的内容和格式,不需要在代码中添加大量注释。
  • 相比 Word 格式的文档,Markdown 格式文档占用的空间更小,能够跟随代码仓库一起发布,方便 API 文档的分发和查找。
  • 相比在线 API 文档编写工具,Markdown 格式的文档免去了第三方平台依赖和网络的限制。

1.4. API 文档规范

一个规范的 API 接口文档,通常需要包含一个完整的 API 接口介绍文档、API 接口变更历史文档、通用说明、数据结构说明、错误码描述和 API 接口使用文档(API 接口使用文档中需要包含接口描述、请求方法、请求参数、输出参数和请求示例)。

当然,根据不同的项目需要,API 接口文档会有不同的格式和内容。一个 API 接口文档示例如下所示,被拆分成若干个 markdown 文件,并放在 docs/guide/zh-CN/api 中。

  • README.md :API 接口介绍文档,会分类介绍支持的 API 接口,并会存放相关 API 接口文档的链接,方便开发者查看。

  • CHANGELOG.md :API 接口文档变更历史,方便进行历史回溯,也可以使调用者决定是否进行功能更新和版本更新。

  • generic.md :用来说明通用的请求参数、返回参数、认证方法和请求方法等。

  • struct.md :用来列出接口文档中使用的数据结构。这些数据结构可能被多个 API 接口使用,会在 user.md、secret.md、policy.md 文件中被引用。

  • user.md 、 secret.md 、 policy.md :API 接口使用文档,相同 REST 资源的接口会存放在一个文件中,以 REST 资源名命名文档名。

    下面以 user.md 接口使用文档为例解释接口使用文档是怎么写的。user.md 这个文件中记录了 user 相关的接口,每个接口按照顺序排列:

    • 接口描述:描述接口实现了什么功能。
    • 请求方法:接口的请求方法,格式为 HTTP 方法请求路径,例如 POST /v1/users。在 通用说明中的请求方法部分,会说明接口的请求协议和请求地址。
    • 输入参数:接口的输入字段,它又分为 Header 参数、Query 参数、Body 参数、Path 参数。每个字段通过:参数名称、必选、类型 和 描述 4 个属性来描述。如果参数有限制或者默认值,可以在描述部分注明。
    • 输出参数:接口的返回字段,每个字段通过参数名称、类型和描述 3 个属性来描述。
    • 请求示例:一个真实的 API 接口请求和返回示例。
  • error_code.md :错误码描述,通过程序自动生成。

更详细的 API 接口文档规范,可参考这个链接:https://github.com/dawnguodev/iam/tree/master/docs/guide/zh-CN/api

1.5. 资料

  1. 在线的 README 生成工具,readme.so;
  2. proto 自动生成 API 文档;
  3. coding API 文档工具或者 yapi;

2. 巨人的肩膀

  1. 极客时间.孔令飞.《Go 语言项目开发实战》