工程实践 on 牛哥聊技术

Spring Boot 配置加载机制详解

Thu, 14 Aug 2025 15:00:00 +0800

几乎每个 Spring Boot 项目都遇到过

排查问题时最让人崩溃的一类故障是——

配置改了重启了，行为还是老的。

经验稍丰富的开发会立刻反应过来：它从别处加载了更高优先级的配置，覆盖了你的修改。但这"别处"具体是哪里？覆盖顺序是什么？为什么有些配置改了没生效，有些反而立刻生效？

Spring Boot 的配置加载体系在文档里写得相对分散，本文把它完整拉直说一遍——从 application.yml 到环境变量、从 bootstrap.yml 到 EnvironmentPostProcessor、从 --server.port=8080 到 K8s ConfigMap，把所有渠道按优先级排成一张图。

一、Spring Boot 配置的"位置"全集

Spring Boot 能从这些地方读取配置（优先级从高到低）：

flowchart TD
 A["1. 命令行参数
--server.port=8080"]
 B["2. SPRING_APPLICATION_JSON
JSON 串注入"]
 C["3. ServletConfig / ServletContext 参数"]
 D["4. JNDI 属性"]
 E["5. Java System Properties
-Dxxx=yyy"]
 F["6. OS 环境变量
SERVER_PORT=8080"]
 G["7. RandomValuePropertySource
random.*"]
 H["8. 外部 application.yml
(jar 包外)"]
 I["9. 外部 application-{profile}.yml"]
 J["10. 内部 application.yml
(jar 包内)"]
 K["11. 内部 application-{profile}.yml"]
 L["12. @PropertySource 注解"]
 M["13. 默认值
SpringApplication.setDefaultProperties"]

 A --> B --> C --> D --> E --> F --> G --> H --> I --> J --> K --> L --> M

优先级越靠上的源覆盖越靠下的源——同一个 key 多处定义时，最高优先级的值生效。

记住一个原则：

“外部覆盖内部、命令行覆盖文件、Profile 覆盖默认”——这三句话覆盖了 95% 的优先级问题。

二、为什么命令行优先级最高

Spring Boot 把命令行优先级设到最高，是为了给运维一个『不需要改代码也能改配置』的口子：

1

java -jar app.jar --server.port=9999 --spring.datasource.url=...

无论 jar 包里 application.yml 写了什么，命令行说了算。

K8s 里也是这个意思——通过 ConfigMap 传环境变量，环境变量优先级高于 jar 内配置，就实现了"同一个 jar 部署到不同环境"。

三、application.yml 在哪些位置会被找到

Spring Boot 启动时按以下顺序查找配置文件（Spring Boot 2.3+ 默认）：

1
2
3
4
5


1. file:./config/*/ (运行目录 config 下的一级子目录,2.3+ 起最高优先级)
2. file:./config/ (运行目录的 config 子目录)
3. file:./ (运行目录)
4. classpath:/config/ (jar 内的 config/)
5. classpath:/ (jar 内根目录)

file: 开头表示文件系统位置
classpath: 是 jar 包内
越靠前的位置优先级越高
file:./config/*/ 经常被忽视——K8s 把多个 ConfigMap 分别挂到 config/redis/、config/db/ 等子目录时，就靠这一项被加载

这就是为什么"jar 同级目录放 application.yml"能覆盖 jar 内配置——是 #2 覆盖 #4 的体现。

文件名默认是 application，可以通过 spring.config.name 改：

1

java -jar app.jar --spring.config.name=myapp

会去找 myapp.yml / myapp.properties。

spring.config.location 能完全自定义查找路径：

1

java -jar app.jar --spring.config.location=file:/etc/myapp/

四、Profile 机制：环境维度切换

激活 Profile

1

java -jar app.jar --spring.profiles.active=prod

或者环境变量：

1

SPRING_PROFILES_ACTIVE=prod java -jar app.jar

Profile 文件命名

1
2
3
4


application.yml ← 共享配置
application-dev.yml ← dev profile 独占
application-test.yml ← test profile 独占
application-prod.yml ← prod profile 独占

激活某个 profile 时，application.yml 和 application-{profile}.yml 都会被加载，profile 文件覆盖通用文件。

多 Profile 同时激活

1

--spring.profiles.active=prod,monitoring,debug

按数组顺序加载，后面的覆盖前面的。这是做"基础 prod 配置 + 加监控 + 加调试日志"组合的标准姿势。

`spring.profiles.include`

不同于 active 是"激活什么"，include 是"再附加什么"：

1
2
3
4


# application-prod.yml
spring:
 profiles:
 include: monitoring

激活 prod 时自动也加载 application-monitoring.yml——保证一组配置成套生效，不用每次写命令行参数。

五、`bootstrap.yml` vs `application.yml`

Spring Cloud 项目里还会出现 bootstrap.yml——它是 Spring Cloud 引入的，比 application.yml 更早加载。

flowchart LR
 A[bootstrap.yml
加载阶段 1] --> B[拉取远程配置中心]
 B --> C[application.yml
加载阶段 2]
 C --> D[最终 Environment]

bootstrap.yml 的典型用途——配置"配置中心客户端本身"：

1
2
3
4
5
6
7
8
9


# bootstrap.yml
spring:
 application:
 name: user-service
 cloud:
 nacos:
 config:
 server-addr: nacos.internal:8848
 namespace: prod

为什么必须更早加载？因为 Nacos / Apollo / Spring Cloud Config 的客户端要先连上配置中心，才能拉到 application.yml 里的业务配置——鸡生蛋、蛋生鸡的问题。

Spring Cloud 2020.0 之后官方推荐用 spring.config.import 替代 bootstrap.yml：
1
2
3
spring:
 config:
 import: optional:nacos:application.yml
但 bootstrap.yml 仍然兼容，且大量老项目还在用。

六、外部化配置：12-Factor 的最佳实践

12-Factor App 第三条：“Store config in the environment”——配置应当从环境而来，而不是写死在代码里。Spring Boot 的设计完全贴合这个理念：

1
2
3
4
5
6


# application.yml
spring:
 datasource:
 url: ${DB_URL:jdbc:mysql://localhost:3306/test}
 username: ${DB_USER:root}
 password: ${DB_PASS:}

${VAR:default} 语法——先看环境变量，没有就用默认值。这种写法的好处：

同一个 jar 在 dev/test/prod 三套环境跑
K8s 里通过 ConfigMap / Secret 注入
本地开发不需要 Secret，用默认值

K8s 部署时：

1
2
3
4
5
6
7
8


env:
 - name: DB_URL
 value: jdbc:mysql://prod-mysql:3306/order
 - name: DB_PASS
 valueFrom:
 secretKeyRef:
 name: db-secret
 key: password

七、`@Value` vs `@ConfigurationProperties`

业务代码注入配置有两种主流方式。

`@Value`：单字段注入

1
2


@Value("${server.port:8080}")
private int port;

简单直接，但有几个限制：

不支持类型校验——拼写错了运行时才发现
不支持嵌套对象——只能拿单个值
不便于测试——要在 test 里 mock 整个 Environment

`@ConfigurationProperties`：批量映射

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


@Component
@ConfigurationProperties(prefix = "feature")
@Validated
public class FeatureConfig {
 @NotBlank
 private String name;
 @Min(0) @Max(100)
 private int threshold;
 private Map<String, String> tags;

 // getters / setters
}

1
2
3
4
5
6


feature:
 name: my-feature
 threshold: 50
 tags:
 region: cn
 env: prod

@ConfigurationProperties 是生产推荐姿势——类型安全、能 @Validated 校验、IDE 提示完整、便于单元测试。

`@RefreshScope`

配置中心场景下，要让配置变更立刻生效需要加 @RefreshScope：

1
2
3
4


@Component
@RefreshScope
@ConfigurationProperties(prefix = "feature")
public class FeatureConfig { ... }

但记住：

@RefreshScope 不要加在 @Configuration 上
@ConfigurationProperties 自带的刷新已经够多数场景用，不一定需要 @RefreshScope
复杂业务的"动态配置"建议直接通过事件订阅，而不是依赖 @RefreshScope 重建 Bean

八、调试技巧：搞清楚配置从哪里来

1. Actuator 的 `/actuator/env`

1
2
3
4
5


management:
 endpoints:
 web:
 exposure:
 include: env,configprops

调用 /actuator/env 能看到每个 PropertySource、每个 key 的来源和最终值——是排查"配置不生效"的最快办法。

1
2
3
4
5
6


{
 "name": "applicationConfig: [classpath:/application.yml]",
 "properties": {
 "server.port": { "value": 8080 }
 }
}

2. 启动日志 DEBUG

1

java -jar app.jar --debug

会打出每个 starter 的自动配置生效情况。

3. 启动参数检查

如果你怀疑有命令行参数在覆盖配置，看启动脚本里的所有 -D 和 --，再看环境变量：

1

env | grep -i SPRING

很多"诡异覆盖"是 K8s ConfigMap 里悄悄塞了同名变量。

九、几个最常被踩的坑

坑 1：YAML 缩进与冒号后空格

1
2


server:
 port:8080  # ❌ 冒号后没空格 → 当作字符串

1
2


server:
 port: 8080 # ✓

坑 2：Profile 里的相对路径

1
2
3
4


# application-prod.yml
logging:
 file:
 name: logs/app.log  # 相对路径，相对于"工作目录"，不是项目目录

部署到容器后工作目录可能不是你以为的位置——生产路径写绝对路径。

坑 3：环境变量大小写转换

YAML 里的 spring.datasource.url 对应环境变量是 SPRING_DATASOURCE_URL——点变下划线、全大写。写成 spring.datasource.url 当环境变量是不会被认到的（虽然 Spring Boot 现在支持驼峰转 kebab，但环境变量必须全大写）。

坑 4：占位符递归

1
2


foo: ${bar}
bar: ${foo}  # ❌ 死循环

启动直接报错。但更隐蔽的是：

1
2
3


prefix: app
fullName: ${prefix}-${name:default}
name: ${prefix}-suffix

会展开成预期之外的字符串，自己看不出来。复杂占位符建议拉直写。

坑 5：`@ConfigurationProperties` 没生效

最常见原因是没加 @Component 或 @EnableConfigurationProperties：

1
2
3


@Component
@ConfigurationProperties(prefix = "feature")
public class FeatureConfig { ... }

或者：

1
2
3


@Configuration
@EnableConfigurationProperties(FeatureConfig.class)
public class AppConfig { ... }

二者选其一。

十、生产 Checklist

部署前过一遍：

不在代码 / yml 里硬编码密钥、数据库密码
敏感配置通过环境变量 / Secret 注入
不同环境分别有 application-{env}.yml
--spring.profiles.active 在启动脚本明确传入
业务代码用 @ConfigurationProperties + @Validated
路径相关配置写绝对路径
Actuator env 和 configprops 在生产环境关闭或加权限
大型项目的全局配置走 bootstrap.yml 或 spring.config.import
启动后用 /actuator/env 抽查关键配置的来源

小结

把全文压一句：

Spring Boot 配置加载的本质是『多个 PropertySource 按优先级合并』——只要把『谁覆盖谁』这件事弄明白，所有"配置不生效"的问题都能 5 分钟定位。

记住几条核心规则：

优先级：命令行 > 环境变量 > 外部文件 > 内部文件 > 默认值
Profile：通用 + profile 配置都加载，profile 覆盖通用
业务用 @ConfigurationProperties，少用 @Value
配置中心走 bootstrap.yml / spring.config.import
排查用 /actuator/env

把这些吃透，配置层基本不会再出意外。

软件研发生命周期中的核心文档梳理

Tue, 06 May 2025 17:48:31 +0800

软件研发生命周期中的核心文档梳理

在软件研发项目的全流程中，文档是一项不可或缺的支撑工具。它们不仅仅是“凭证”，更是团队协作、需求澄清、技术落地、交付和维护的重要桥梁。对于管理者、产品、开发、测试乃至运维等不同角色，理解并正确使用每类文档，能有效提升项目的效率和质量。本文将对研发生命周期各阶段的主流文档进行梳理，着重说明其主要作用、使用场景和典型使用角色。

1. 项目启动与可行性分析阶段

1.1 项目建议书/立项文档

主要作用：明确项目背景、预期目标和价值，论证开展该项目的合理性和必要性。
使用场景：项目正式启动前，项目申报、资源争取、重大决策时。
典型角色：项目负责人、高管、产品经理、业务方。

模板文件：查看项目建议书模板

1.2 可行性分析报告（可选）

主要作用：多维度分析项目在技术、经济、资源、合规等方面的可行性与主要风险。
使用场景：创新性较强、规模较大的项目立项评审阶段。
典型角色：架构师、技术负责人、项目管理。

模板文件：查看可行性分析报告模板

2. 需求分析阶段

2.1 业务需求文档/需求调研报告

主要作用：全面记录用户实际业务流程、关键需求与问题点，从业务视角定义系统边界。
使用场景：需求调研、业务梳理、需求评审前期。
典型角色：业务分析师、产品经理、客户代表。

模板文件：查看业务需求文档模板

2.2 软件需求规格说明书（SRS）

主要作用：作为开发、测试、验收等一切后续工作的正式依据，将功能与非功能需求精确落地。
使用场景：需求评审、开发前需求冻结、变更管理、测试验收。
典型角色：产品经理、开发、测试、项目管理。

模板文件：查看软件需求规格说明书模板

2.3 原型图 / 交互设计文档（可选）

主要作用：通过界面视觉化，帮助各方对齐功能预期和操作流程，提高需求沟通效率。
使用场景：需求澄清、界面评审、前后端协作。
典型角色：产品经理、UI/UX设计师、开发、测试。

模板文件：查看原型图/交互设计文档模板

3. 设计阶段

3.1 概要设计说明书（High-Level Design, HLD）

主要作用：定义系统总体架构、模块划分、主要逻辑流程和关键技术选型，为详细设计和开发奠定基础。
使用场景：设计方案评审、团队分工、技术决策。
典型角色：架构师、技术负责人、开发主程、项目经理。

模板文件：查看概要设计说明书模板

3.2 详细设计说明书（Low-Level Design, LLD）

主要作用：细致描述各个模块/功能的实现细节，包括数据结构、接口、核心算法和异常处理，为具体编码提供指引。
使用场景：开发任务分解、代码编写前、Code Review。
典型角色：开发主程、开发工程师、测试人员、架构师。

模板文件：查看详细设计说明书模板

4. 实现与测试阶段

4.1 测试用例说明书 / 测试计划

主要作用：明确验证每一条需求和功能点的具体方式，涵盖正常/异常流程与边界场景。
使用场景：测试设计、开发自测、回归测试、验收测试。
典型角色：测试工程师、开发自测、产品经理。

模板文件：查看测试计划模板

4.2 测试报告

主要作用：汇总测试执行结果与缺陷情况，为产品发布与质量判断提供依据。
使用场景：测试完成后、阶段性评审、最终上线决策。
典型角色：测试工程师、项目经理、开发负责人。

模板文件：查看测试报告模板

5. 上线与运维阶段

5.1 发布手册/上线方案

主要作用：规范发布流程，明确上线操作步骤、注意事项、回滚与应急措施。
使用场景：系统上线、版本发布、运维流程梳理。
典型角色：运维工程师、开发、实施人员。

模板文件：查看发布手册/上线方案模板

5.2 用户手册/操作说明

主要作用：指导终端用户或业务方规范使用系统，降低培训和支持成本。
使用场景：新系统推广、用户培训、客户支持。
典型角色：产品经理、技术支持、终端用户。

模板文件：查看用户手册/操作说明模板

5.3 运维手册/技术支持文档

主要作用：梳理系统部署、监控、常见故障排查和恢复流程。
使用场景：系统上线运维、快速排障、知识传承。
典型角色：运维工程师、技术支持、开发团队。

模板文件：查看运维手册/技术支持文档模板

结语

文档贯穿软件研发全流程，不同文档的侧重点各有不同，针对的使用场景和主要角色也各异。正确理解和高效利用这些文档，有助于团队协作、信息传递和项目质量管控。不论项目大小，适度、规范、持续更新的文档体系，都是实现高质量交付与维护的关键保障。

如何把 Go 模块文档发布到 pkg.go.dev

Thu, 05 Oct 2023 15:30:00 +0800

写在前面

Go 生态里没有 npm registry / Maven Central 这种"集中仓库"——Go 模块直接通过 git 仓库地址拉取：

1

go get github.com/lingcoder/go-fsm

但有一个东西扮演了"官方文档站"的角色——pkg.go.dev。它不存代码，只存文档——从你的 Go 源码自动生成。

如果你写了一个 Go 库想让人用，go get 能拉到不代表你"发布了"——pkg.go.dev 上有完整文档、版本列表、示例代码、依赖图，才是 Go 生态意义上的"发布"。

本文用我自己的 go-fsm 作为例子，把发布流程、文档规范、版本管理讲清楚。

一、pkg.go.dev 是什么

它是 Google 维护的 Go 模块文档中心：

自动从 GitHub / GitLab 拉取公开 Go 模块
解析源码生成 HTML 文档
显示版本列表、license、依赖图、被引用数
支持搜索、跳转、链接到源码

flowchart LR
 GitHub[GitHub Tag] --> Proxy[proxy.golang.org]
 Proxy --> PkgGoDev[pkg.go.dev]
 PkgGoDev --> Doc[文档站]

你不需要"提交"什么——只要模块能被 go get，pkg.go.dev 就会自动收录。

二、最小可发布的 Go 模块

1. 仓库结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


go-fsm/
├── go.mod
├── go.sum
├── LICENSE
├── README.md
├── doc.go # 包级文档
├── fsm.go # 主代码
├── fsm_test.go
└── examples/
 └── basic/
 └── main.go

2. go.mod

1
2
3


module github.com/lingcoder/go-fsm

go 1.21

module 名必须是仓库的 import path——pkg.go.dev 通过这个找到对应的 git 仓库。

3. doc.go：包级文档

 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


// Package fsm provides a lightweight, type-safe finite state machine
// implementation for Go applications.
//
// # Quick Start
//
// Define states and events:
//
// const (
// StatePending = fsm.State("pending")
// StateApproved = fsm.State("approved")
// StateRejected = fsm.State("rejected")
// )
//
// m := fsm.New(StatePending).
// On(EventApprove).From(StatePending).To(StateApproved).
// On(EventReject).From(StatePending).To(StateRejected).
// Build()
//
// # Features
//
// - Type-safe state and event definitions
// - Hooks before / after transitions
// - Concurrent-safe by default
// - Zero dependencies
package fsm

doc.go 里的 package 注释会成为 pkg.go.dev 主页的描述——它是用户对你库的第一印象。

4. README.md

pkg.go.dev 会同时展示 README 与包级 doc——README 显示在首页 Overview 区，包级 doc 显示在 Documentation 区。两者各司其职：README 面向 GitHub / pkg.go.dev 访客做项目介绍，doc.go 面向 godoc / IDE 跳转做 API 文档。建议把 GitHub 风格的徽章、功能 GIF、安装命令放 README，把 API 用法和 example 放 doc.go。

三、文档规范：让 godoc 漂亮

pkg.go.dev 的文档完全从 Go 源码注释生成——注释规范决定文档质量。

1. 每个导出符号都要有注释

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// State represents a state in the finite state machine.
type State string

// Event represents a transition trigger event.
type Event string

// FSM is a finite state machine instance.
type FSM struct {
 current State
 // ...
}

// New creates a new FSM with the given initial state.
func New(initial State) *FSM {
 return &FSM{current: initial}
}

注释必须以符号名开头——这是 godoc 的强约定。

2. 多行注释

1
2
3
4
5
6
7
8
9


// Trigger fires an event and transitions the FSM.
//
// If no transition is defined for the current state and event,
// it returns an ErrNoTransition error.
//
// Trigger is safe for concurrent use.
func (m *FSM) Trigger(e Event) error {
 // ...
}

空行分段，每段一个意思。

3. 列表

1
2
3
4
5


// Available hooks:
//
// - BeforeTransition: called before state changes
// - AfterTransition: called after state changes
// - OnError: called when transition fails

注意——列表项前要有 4 空格缩进，pkg.go.dev 才会渲染成 bullet。

4. 可执行示例

example_*.go 文件里的 Example* 函数会自动出现在 pkg.go.dev：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


// example_test.go
package fsm_test

import (
 "fmt"
 "github.com/lingcoder/go-fsm"
)

func ExampleFSM_Trigger() {
 m := fsm.New("pending").
 On("approve").From("pending").To("approved").
 Build()

 m.Trigger("approve")
 fmt.Println(m.State())
 // Output: approved
}

// Output: ... 是 Go 测试框架的语法——它既验证示例正确性，也是文档。

5. 标题（Go 1.19+）

1
2
3
4
5
6
7


// # Configuration
//
// The FSM can be configured via options...

// # Performance
//
// The FSM is optimized for...

# 在注释里被识别为标题——pkg.go.dev 会渲染成大标题、生成目录。

四、版本管理：发布正式版本

1. 用 git tag 发布

1
2


git tag v1.0.0
git push origin v1.0.0

tag 必须是 vX.Y.Z 格式——Go modules 强制语义化版本。

2. 让 pkg.go.dev 收录新版本

打 tag 后，第一次访问 https://pkg.go.dev/github.com/lingcoder/go-fsm@v1.0.0 会触发proxy.golang.org 抓取——几秒后页面就有了。

或者用：

1

go get github.com/lingcoder/go-fsm@v1.0.0

也会触发同样的抓取。

3. v2+ 的特殊规则

重要：v2 及以上版本要在 module path 里加版本号：

1
2
3


v0.x.x / v1.x.x → module path: github.com/lingcoder/go-fsm
v2.x.x → module path: github.com/lingcoder/go-fsm/v2
v3.x.x → module path: github.com/lingcoder/go-fsm/v3

发布 v2 时：

1
2
3
4


# go.mod
module github.com/lingcoder/go-fsm/v2

go 1.21

并打 tag v2.0.0。这是 Go 1.13 之后的强制规则——强迫"breaking change 必显式"。

五、license 文件：影响排名

pkg.go.dev 会显示模块的 license——有 license 的模块在搜索结果里更靠前。最常用：

MIT —— 最宽松，工业首选
Apache 2.0 —— 带专利授权条款，大公司喜欢
BSD-3-Clause —— 简单、宽松

把对应的 LICENSE 文件放仓库根目录就行——pkg.go.dev 自动识别。

没 license 的代码 法律上等于"All rights reserved" ——别人不能用。开源前一定要加。

六、CI 集成：自动化发布

GitHub Actions 自动测试 + 发版：

 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


# .github/workflows/release.yml
name: release

on:
 push:
 tags: ['v*']

jobs:
 release:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v3
 - uses: actions/setup-go@v4
 with:
 go-version: '1.21'

 - name: Test
 run: go test ./...

 - name: Vet
 run: go vet ./...

 - name: Trigger pkg.go.dev fetch
 run: |
 curl -sSf "https://proxy.golang.org/github.com/${{ github.repository }}/@v/${{ github.ref_name }}.info"

最后一步主动告诉 proxy.golang.org 拉取——比等用户访问快。

七、提高搜索排名

pkg.go.dev 的搜索排名考虑：

被 import 数量——其他 Go 模块依赖你的越多，排名越高
license 是否存在
文档完整度——所有导出符号都有注释
版本稳定——是否打过 v1+ tag
README / doc.go 内容——关键词是否覆盖搜索词

策略：

取好搜的名字（关键词命中度高）
早发 v1.0.0——pkg.go.dev 把 0.x 版本视为不稳定
写好 doc.go——是搜索引擎的主要食粮
写 example——示例丰富的库更受欢迎

八、常见问题

1. 推了 tag 但 pkg.go.dev 没显示

主动触发抓取：

1

curl "https://proxy.golang.org/github.com/your/repo/@v/v1.0.0.info"

或访问一次 https://pkg.go.dev/github.com/your/repo@v1.0.0。

2. README 里的图片不显示

pkg.go.dev 会渲染 README，但不加载相对路径的本地图片——![logo](docs/logo.png) 这种引用在 pkg.go.dev 上看不到。要让图片正常显示：

用 GitHub raw 的绝对 URL：![logo](https://raw.githubusercontent.com/owner/repo/main/docs/logo.png)
或者把图片放在 GitHub Pages / 图床上引用

API 文档建议同时维护 README（项目介绍）和 doc.go（API 用法）——两者会分别在 Overview 区和 Documentation 区展示，互不替代。

3. 私有仓库怎么办

私有 module 不会在 pkg.go.dev 出现。要内部 doc：

自托管 godoc -http=:6060
公司内部用 pkgsite 自建

4. 删除已发布版本

不能删除。一旦 tag 发布到 proxy.golang.org，会被永久缓存——这是 Go modules 的"checksum 不可变"承诺。

发现版本有 bug：

标记 retract（go.mod 里加 retract v1.0.5）
立刻发新版本 v1.0.6 修复

1
2
3
4
5
6


// go.mod
module github.com/lingcoder/go-fsm

go 1.21

retract v1.0.5 // bug, use v1.0.6+

retracted 版本仍能解析，但用户用 go get 时会得到警告。

5. examples 怎么组织

简单示例 → example_test.go（pkg.go.dev 显示）
完整 demo → examples/ 目录（GitHub 显示但 pkg.go.dev 不显示——所以 doc.go 里指向）

九、一份发布前 Checklist

发版前对照检查：

go.mod 的 module path 正确
doc.go 写好包级文档
所有导出符号有注释（用 golint / revive 检查）
LICENSE 文件存在
README.md 包含安装、quickstart、license
至少 3 个 Example 函数
单元测试覆盖关键路径
CI 通过
打 v1.0.0+ tag（或符合 v2+ 规则）
推 tag 后访问 pkg.go.dev 验证

小结

把全文压一句：

Go 模块发布的『正式仪式』是 git tag + pkg.go.dev——但真正决定库能否被人用的是 doc.go 和 Example 函数的质量。

工程要点：

注释以符号名开头，每个导出符号都有
doc.go 是包的脸面——花时间写
Example 函数比一万字文档有效
v1.0.0 是分水岭——别永远停在 0.x
v2+ 必改 module path

把这套做对，你的 Go 库就不只是"能 go get"——它有文档、有版本、有声誉，是 Go 生态的"正式公民"。

Conda和poetry搭配使用

Mon, 11 Sep 2023 18:07:52 +0800

创建一个新的conda环境，并在这个环境中使用 poetry。这是为了防止conda环境和poetry环境之间有冲突，或者因为全局系统级别的Python和包影响项目。

步骤：

创建conda环境（此处的myenv是环境名，3.11是你需要的Python版本）：

1

conda create -n myenv python=3.11 --no-default-packages

激活这个conda环境：

1

conda activate myenv

确认你正在使用conda环境中的Python。在终端输入以下命令，查看python路径：

1

which python

你应该可以看到一个指向你刚创建的conda环境的路径。

现在，你应该可以在你的conda环境中安装和使用 poetry 了。可以通过以下命令来安装 poetry：

1

pip install poetry

当我们在conda环境中启动了poetry后，可以创建一个新的poetry项目，或切换到已有的poetry项目目录下，然后使用 poetry install 安装项目的依赖。由于你是在conda环境中启动的 poetry，所以依赖会被安装在当前的conda环境中。请注意，使用这种方式，conda会负责管理Python和二进制依赖，而poetry则负责管理Python包。

最后，附赠一份poetry项目常用的镜像构建脚本：

 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



FROM python:3.11-bookworm as builder

WORKDIR /app

COPY pyproject.toml poetry.lock /app/

ENV POETRY_VIRTUALENVS_CREATE false

RUN pip3 install pip --upgrade && pip3 install poetry --upgrade && poetry install --no-root --only main


FROM python:3.11-slim-bookworm

WORKDIR /app

COPY --from=builder /usr/local/lib/python3.11 /usr/local/lib/python3.11

COPY --from=builder /usr/local/bin/ /usr/local/bin/

COPY . /app

EXPOSE 8080

# Run the application when the container launches
CMD ["python", "main.py"]

Markdown 常见语法整理

Tue, 18 Apr 2023 15:00:00 +0800

为什么写一篇 Markdown 语法 Demo

Markdown 这东西看着简单，写多了你会发现：

不同博客平台、不同文档系统、甚至同一个工具的不同版本，支持的语法和扩展不一致
表格的对齐符号有人记不住
链接、图片、脚注的语法长得像但顺序不一样
代码块的语言标识不写就没高亮
Mermaid、KaTeX、警告框这些"扩展语法"很多人不知道

这篇是给我自己——也给所有用 Markdown 写技术博客的人——一份能直接收藏的速查 + Demo。每一节都给出实际渲染效果，复制即用。

本博客基于 Hugo + hugo-theme-stack，使用 Goldmark 作为 Markdown 渲染器。后文出现的"Hugo/Stack 主题特有"指的就是这套环境。

一、标题

1
2
3
4
5
6


# H1 标题
## H2 标题
### H3 标题
#### H4 标题
##### H5 标题
###### H6 标题

实战建议：

博客文章不要写 #——文章标题在 front matter 里已经有 title，正文从 ## 开始
层级不要超过 4 级——太深的层级阅读和导航都变差
标题前后留空行，避免渲染粘连

二、行内格式

1
2
3


**粗体** *斜体* ~~删除线~~ `行内代码`
[链接](https://example.com)
**_组合效果_**

渲染：粗体、斜体、~~删除线~~、行内代码、链接。

实战建议：

粗体优于斜体——中文里斜体可读性差
行内代码用反引号——API、UserService、createTime 这些标识符都该用
不要滥用粗体——一段里超过 3 处加粗等于没加粗

三、段落与换行

Markdown 用空行分段，单个换行不是分段：

1
2
3
4


这是第一段。
这一行虽然换行了，但还在第一段。

这是第二段。

如果真要在一段内强制换行（不分段），用两个空格 + 换行：

1
2


第一行末尾两个空格 
第二行

或者用 <br> 也行，但能不用就不用。

四、列表

无序列表

1
2
3
4
5


- 项目一
- 项目二
 - 嵌套项目
 - 又一个嵌套
- 项目三

有序列表

1
2
3


1. 第一步
2. 第二步
3. 第三步

任务列表（GFM）

1
2
3
4


- [x] 完成需求评审
- [x] 写代码
- [ ] 写单元测试
- [ ] 写文档

渲染：

完成需求评审
写代码
写单元测试
写文档

五、链接与图片

1
2
3
4
5
6


[GitHub](https://github.com)
[带 title](https://github.com "悬浮提示")
[相对链接](../another-post/)

![图片描述](path/to/image.png)
![图片带 title](path/to/image.png "图片悬浮文字")

实战建议：

图片描述（alt）一定要写——SEO + 无障碍 + 加载失败时显示
优先用相对路径——博客域名换了不会失效
大图用 Hugo 的 image processing： shortcode

六、引用块

1
2
3
4
5
6


> 这是引用的第一行。
> 这是引用的第二行。
>
> > 嵌套引用。

> **加粗的引用**——可以包含其他格式。

渲染：

这是引用的第一行。这是引用的第二行。

嵌套引用。

引用最常用的场景是：

标记别人的话（“鲁迅说……"）
强调结论
给小贴士/重要提示加个视觉标签

七、代码块

1
2
3
4
5
6
7


\`\`\`java
public class Hello {
 public static void main(String[] args) {
 System.out.println("Hello, world!");
 }
}
\`\`\`

渲染：

1
2
3
4
5


public class Hello {
 public static void main(String[] args) {
 System.out.println("Hello, world!");
 }
}

实战建议：

永远写语言标识——java、python、bash、yaml、json、sql，否则没语法高亮
不要在代码块里写废话注释——读者要的是能跑的代码
复制按钮：本博客主题渲染时自带，无需额外标记

八、表格

1
2
3
4


| 列 1 | 列 2 | 列 3 |
| :----- | :----: | -----: |
| 左对齐 | 居中 | 右对齐 |
| 内容 A | 内容 B | 内容 C |

渲染：

列 1	列 2	列 3
左对齐	居中	右对齐
内容 A	内容 B	内容 C

对齐规则：

:---：左对齐
:---:：居中
---:：右对齐
---：默认（左）

九、分隔线

1

---

或者：

1
2


***
___

效果都一样：

十、转义字符

要在文中显示 Markdown 的特殊字符，用 \ 转义：

1
2
3
4


\* 这不是斜体
\` 这不是代码
\[ 这不是链接
\# 这不是标题

十一、Mermaid 图（Hugo Stack 主题支持）

1
2
3
4
5
6
7
8


```mermaid
flowchart LR
 A[开始] --> B{判断}
 B -->|是| C[执行]
 B -->|否| D[跳过]
 C --> E[结束]
 D --> E
```

渲染：

flowchart LR
 A[开始] --> B{判断}
 B -->|是| C[执行]
 B -->|否| D[跳过]
 C --> E[结束]
 D --> E

Mermaid 支持的图类型很多——流程图、时序图、类图、ER 图、甘特图、状态机。日常写技术博客最常用的是 flowchart、sequenceDiagram、classDiagram 三种。

时序图示例

sequenceDiagram
 Client->>Server: HTTP 请求
 Server->>DB: 查询
 DB-->>Server: 结果
 Server-->>Client: HTTP 响应

类图示例

classDiagram
 class Animal {
 +String name
 +eat()
 }
 class Dog {
 +bark()
 }
 Animal <|-- Dog

甘特图示例

项目排期、迭代计划用甘特图表达最直观：

gantt
 dateFormat YYYY-MM-DD
 title 项目排期

 section 需求阶段
 需求评审 :done, a1, 2023-04-01, 5d
 原型设计 :done, a2, after a1, 4d

 section 开发阶段
 后端 API :active, b1, 2023-04-12, 10d
 前端页面 : b2, after a2, 8d

 section 测试 & 发布
 联调测试 : c1, after b1, 5d
 上线 :crit, c2, after c1, 1d

十二、KaTeX 数学公式（需 `math: true`）

文章 front matter 里设置 math: true，就能写 LaTeX 公式：

1
2
3
4
5
6
7


行内：$E = mc^2$

块级：

$$
\int_{a}^{b} f(x)\,dx = F(b) - F(a)
$$

渲染需要主题加载 KaTeX——本主题原生支持。不需要数学的文章不要打开 math，加载 KaTeX 会拖慢页面。

十三、HTML 嵌入（默认禁用）

很多 Markdown 工具默认允许在 Markdown 里写 HTML：

1
2
3
4


<details>
<summary>点击展开</summary>
这里是隐藏内容。
</details>

但 Hugo 的 Goldmark 默认 unsafe = false——HTML 会被静默丢弃。如果业务需要嵌入 HTML：

改 markup.toml 把 unsafe = true（小心 XSS）
用 Hugo Shortcode（推荐）

十四、Shortcodes（Hugo 特有）

Hugo 提供了 shortcode 机制——比 HTML 安全，比 Markdown 强大。Hugo 内置了若干常用 shortcode：

1
2
3
4
5


{{< figure src="cover.png" caption="封面图" >}}

{{< youtube id="VIDEO_ID" >}}

{{< gist USERNAME GIST_ID >}}

上面代码块里的 {{< ... >}} 是 Hugo 在文档中展示 shortcode 不被解析的转义写法——实际使用时去掉里面的 /* */。

各主题也常自带专属 shortcode，比如折叠块、提示框、画廊等——具体可见自家主题文档。

十五、其他扩展语法

下面这几个不属于 CommonMark 核心，但 Hugo Goldmark + 主流博客引擎多数支持。

上标 / 下标

1
2
3


面积 = 长 × 宽，公式记作 S = a^2^

化学式：H~2~O，CO~2~

需要在 markup.toml 的 [markup.goldmark.extensions] 下打开 superscript / subscript 扩展。

脚注

1
2
3
4


正文里挂一个脚注[^1]，再补一个[^note]。

[^1]: 这是脚注内容，会出现在文章最末。
[^note]: 命名脚注也可以。

渲染时上标会变成可点击的链接，跳到文末的脚注列表——适合放参考文献、补充说明。

任务列表（再提一次）

很多 Markdown 教程把任务列表算扩展——但 GFM 已经标准化，所有现代渲染器都支持，前文已展示。

表格对齐与多行

复杂表格需要对齐符号 + 每个单元格不要换行——| 必须在同一行。需要单元格内换行用 <br>（要求 unsafe = true 或主题支持）。

十六、写作时的几条小建议

1. 段首不要直接进代码块

1
2
3
4


## 标题

```java
// 反面教材：紧贴标题就是代码

 1
 2
 3
 4
 5
 6
 7
 8
 9
10



正确写法是：

```markdown
## 标题

下面是核心代码：

```java
// 代码

1
2
3
4
5
6
7
8
9



读者需要"前置上下文"才知道这段代码要看什么。

### 2. 列表里包含代码块要缩进

```markdown
1. 第一步：
 ```bash
 git clone xxx

第二步：
1

cd xxx

 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



否则代码块会"破"出列表。

### 3. 中英文之间留空格

虽然 Markdown 不强制，但中英文之间留空格能显著提高可读性：

| 写法 | 效果 |
| :---------------------- | :--------- |
| 用Spring Boot开发 | 别扭 |
| 用 Spring Boot 开发 | 顺眼 |

也可以用 [autocorrect](https://github.com/huacnlee/autocorrect) 这种工具自动加空格。

### 4. 引用图床要慎重

直接 `![](https://外部图床/xxx.png)` 看着方便，但：

- 图床可能挂掉，文章变残
- 防盗链
- 加载速度

**博客图片最好用相对路径放在 page bundle 里**，由 Hugo 处理。

---

## 十七、调试技巧

### 看一篇博客的渲染源码

浏览器右键"查看页面源代码"——看一下 HTML 是怎么生成的。Hugo 的 Goldmark 有很多细节（自动加 ID、表格滚动包装、代码块复制按钮）都体现在 HTML 上。

### 本地预览

```bash
hugo server -D

实时看渲染效果，比每次 push 上线快得多。

Lint 工具

markdownlint 可以检查格式——空行、标题层级、列表缩进——保持风格一致。

小结

把全文压一句：

Markdown 看似自由，但写技术博客时风格、扩展、可移植性都要管。能用通用语法就别上扩展，必须用扩展时优先选有 fallback 的（Mermaid、KaTeX 都行）。

留几条作为"硬性规范”：

代码块永远标语言
图片永远写 alt 描述
中英文之间留空格
标题层级不超过 4 级
任务列表 / 表格对齐符 / 链接相对路径——这些常用语法记牢

最后——Markdown 不是设计文档语言，是写作语言。它的所有特性都为"专注内容"服务。当你开始想"这个怎么用 Markdown 表达"，先问一下"这个真的需要表达吗"。

Makefile 在现代项目的价值与实践

Thu, 22 Oct 2020 15:00:00 +0800

为什么每个项目都该有一份 Makefile

很多人以为 Makefile 是 C/C++ 时代的产物——其实它在 Java / Go / Python / 前端 项目里同样好用。

它的真正价值不在"编译"，而在让项目所有日常操作都有"一行命令入口"：

1
2
3
4
5
6


make run # 启动
make test # 跑测试
make lint # 静态检查
make build # 构建产物
make image # 打 Docker 镜像
make deploy # 发布

新人入职第一天看一眼 Makefile，就知道这个项目能干啥、怎么开始。没有 Makefile 的项目，新人靠口口相传或翻 README，效率差得不是一点半点。

本文讲清楚 Makefile 的核心语法、现代项目里的写法、和那些容易踩的坑。

一、Makefile 的最小可用版

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


# Makefile
.PHONY: help run test build clean

help:
	@echo "Available commands:"
	@echo " make run - Run the application"
	@echo " make test - Run tests"
	@echo " make build - Build artifact"
	@echo " make clean - Remove artifacts"

run:
	go run main.go

test:
	go test ./...

build:
	go build -o bin/app main.go

clean:
	rm -rf bin/

执行：

1
2


make help
make test

⚠️ 关键陷阱：Makefile 命令前必须是 Tab 字符——空格会报 missing separator 错误。这是 Makefile 最让人崩溃的语法点。

二、核心概念

1. 目标（target）/ 依赖（prerequisite）/ 命令（recipe）

1
2


target: prerequisites
	recipe

例子：

1
2


build: src/main.go
	go build -o bin/app src/main.go

意思——“build 这个目标依赖 main.go，要执行 go build"。Make 会比较 main.go 的修改时间和 bin/app 的修改时间——如果 main.go 没变，重复 make build 不会重新构建。

2. 伪目标（.PHONY）

1
2
3


.PHONY: clean
clean:
	rm -rf bin/

.PHONY 告诉 Make——这不是一个真实文件，永远执行。否则如果项目目录里恰好有个文件叫 clean，make clean 会被识别成"clean 文件已存在，无需重做”——什么都不做。

所有"动作型"目标都要加 .PHONY，这是工程纪律。

3. 变量

1
2
3
4
5
6


APP := myapp
VERSION := $(shell git describe --tags --always)
GO := go

build:
	$(GO) build -ldflags "-X main.Version=$(VERSION)" -o bin/$(APP)

:= 是立即求值（推荐），= 是延迟求值（每次引用才计算，容易意外）。

4. 条件

1
2
3
4
5


GOOS ?= linux
GOARCH ?= amd64

build:
	GOOS=$(GOOS) GOARCH=$(GOARCH) go build -o bin/app

?= 表示"如果没设过就用这个默认值"——可以被命令行覆盖：

1

make build GOOS=darwin GOARCH=arm64

三、现代项目的 Makefile 模板

Go 项目

 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


.PHONY: help run test test-cover lint build image clean

APP := myapp
VERSION := $(shell git describe --tags --always 2>/dev/null || echo "dev")
LDFLAGS := -ldflags "-X main.Version=$(VERSION) -s -w"
DOCKER_TAG := $(APP):$(VERSION)

help:
	@echo "Available commands:"
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' Makefile | awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-20s\033[0m %s\n", $$1, $$2}'

run: ## 启动开发服务器
	go run main.go

test: ## 跑单元测试
	go test ./... -race -v

test-cover: ## 测试 + 覆盖率报告
	go test ./... -coverprofile=coverage.out
	go tool cover -html=coverage.out -o coverage.html

lint: ## 静态检查
	golangci-lint run

build: ## 编译产物
	CGO_ENABLED=0 go build $(LDFLAGS) -o bin/$(APP) main.go

image: ## 打 Docker 镜像
	docker build -t $(DOCKER_TAG) .

clean: ## 清理产物
	rm -rf bin/ coverage.out coverage.html

grep -E ... ## ... 这套是个常用技巧——用注释自动生成 help：

1
2
3
4
5
6
7
8
9


$ make help
Available commands:
 run 启动开发服务器
 test 跑单元测试
 test-cover 测试 + 覆盖率报告
 lint 静态检查
 build 编译产物
 image 打 Docker 镜像
 clean 清理产物

Java Spring Boot 项目

 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


.PHONY: help run test build image deploy clean

APP := myapp
PROFILE ?= dev
TAG := $(shell git rev-parse --short HEAD)

help:
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' Makefile | awk 'BEGIN {FS = ":.*?## "}; {printf " %-12s %s\n", $$1, $$2}'

run: ## 启动应用
	./mvnw spring-boot:run -Dspring-boot.run.profiles=$(PROFILE)

test: ## 单元测试
	./mvnw test

build: ## 打 jar
	./mvnw clean package -DskipTests

image: build ## 打镜像
	docker build -t $(APP):$(TAG) .

deploy: image ## 推送 + 部署
	docker push registry.internal/$(APP):$(TAG)
	kubectl set image deploy/$(APP) $(APP)=registry.internal/$(APP):$(TAG)

clean:
	./mvnw clean
	rm -rf target/

注意 image: build 这种语法——image 依赖 build，所以执行 make image 时会先跑 make build。

前端项目

 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


.PHONY: help dev test lint build preview clean

PM := pnpm

help:
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' Makefile | awk 'BEGIN {FS = ":.*?## "}; {printf " %-12s %s\n", $$1, $$2}'

install: ## 装依赖
	$(PM) install

dev: install ## 开发模式
	$(PM) run dev

test: ## 跑测试
	$(PM) run test

lint: ## ESLint + Prettier 检查
	$(PM) run lint
	$(PM) run format:check

build: install ## 生产构建
	$(PM) run build

preview: build ## 预览构建产物
	$(PM) run preview

clean:
	rm -rf node_modules dist coverage

PM 变量让你能在 npm/yarn/pnpm 间切换——make build PM=npm 即可。

四、写 Makefile 的工程纪律

1. 命令前永远是 Tab

最大的坑——空格 vs Tab。配置编辑器：

1
2
3
4


.editorconfig:
[Makefile]
indent_style = tab
indent_size = 4

2. 所有动作目标都加 .PHONY

不加的话哪天目录里有个同名文件就废了。

3. 命令前加 @ 抑制回显

1
2
3


test:
	@echo "Running tests..."
	go test ./...

不加 @ 的话每条命令都会先打印一遍——输出会很啰嗦。

4. 常用变量放顶部

APP、VERSION、GO、DOCKER_TAG 这种所有人改起来频繁的变量放最上面，方便修改。

5. 提供 help 目标

5 行注释正则就能自动生成——这是 Makefile 体验的一半。

6. 别把环境变量硬编码

1
2
3
4
5
6
7
8


# ❌ 反例
build:
	GOPROXY=https://goproxy.cn go build

# ✓ 推荐
GOPROXY ?= https://goproxy.cn
build:
	GOPROXY=$(GOPROXY) go build

新人换代理时不用改 Makefile。

7. 错误处理

1
2
3


deploy:
	@./scripts/check-env.sh || (echo "env check failed"; exit 1)
	kubectl apply -f deploy.yaml

链式命令默认失败就停，但单独的脚本要显式 check。

五、进阶用法

1. 多目录子项目

1
2
3
4
5
6


SUBDIRS := api worker scheduler

build:
	for dir in $(SUBDIRS); do \
		$(MAKE) -C $$dir build; \
	done

$(MAKE) -C dir target 在子目录跑 make。

2. 多平台交叉编译

1
2
3
4
5
6
7
8
9


PLATFORMS := linux/amd64 linux/arm64 darwin/amd64 darwin/arm64

cross-build:
	@for p in $(PLATFORMS); do \
		os=$$(echo $$p | cut -d/ -f1); \
		arch=$$(echo $$p | cut -d/ -f2); \
		echo "Building for $$os/$$arch..."; \
		GOOS=$$os GOARCH=$$arch go build -o bin/app-$$os-$$arch; \
	done

3. 依赖检查

1
2
3
4
5
6
7


check-tools:
	@command -v go >/dev/null || (echo "go not found"; exit 1)
	@command -v docker >/dev/null || (echo "docker not found"; exit 1)
	@command -v kubectl >/dev/null || (echo "kubectl not found"; exit 1)

build: check-tools
	go build -o bin/app

4. include 子模块

1
2


include scripts/build.mk
include scripts/deploy.mk

把 Makefile 拆成多个文件——主 Makefile 只声明几个高阶目标，细节在子 mk 里。

六、Makefile vs 脚本 vs npm scripts

	Makefile	shell 脚本	package.json scripts
跨平台	△ 需要 make	△ 需要 bash	✓
依赖关系	✓ 内建	✗ 自己写	✗ 自己写
自动跳过未变	✓	✗	✗
可读性	△ 冷门语法	✓	✓
调试	△	✓	✓
已普及度	✓ Linux 自带	✓	△ 仅 Node 项目

给一个建议：

任何项目（不论语言）都该有 Makefile 作为『统一入口』——前端项目可以同时保留 package.json scripts，但 make dev / make test / make build 也应该能跑。这让"新人进项目"和"CI 配置"都极简。

七、Windows 兼容

Makefile 在 Windows 下需要装 make（通过 chocolatey、Git Bash、WSL 都行）。如果团队有 Windows 用户：

1
2
3
4
5
6
7
8


ifeq ($(OS),Windows_NT)
	RM := rmdir /s /q
else
	RM := rm -rf
endif

clean:
	$(RM) bin

或者更简单——让 Windows 用户用 WSL，业务级开发现在已经是默认配置。

八、CI 集成

GitLab CI / GitHub Actions 直接调 make：

1
2
3
4
5
6
7
8
9


# .github/workflows/ci.yml
jobs:
 test:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v3
 - run: make test
 - run: make lint
 - run: make build

CI 配置文件极简——所有逻辑都在 Makefile 里。换 CI 平台（GitLab → GitHub Actions → Jenkins）只要改这一个文件，Makefile 不动。

小结

把全文压一句：

Makefile 不是构建工具，是『项目的遥控器』——让任何人 5 分钟看懂这个项目能做什么、怎么做。

记住几条：

命令前是 Tab 不是空格——这是 Makefile 第一坑
所有动作目标加 .PHONY
写 help 目标——用注释 + grep 自动生成
变量放顶部，外部可覆盖
CI 直接调 make——配置文件不要重复逻辑

把项目里那些"git 仓库下完不知道怎么跑"的痛点用 Makefile 一次性解决——这是最便宜的体验提升。

Git和GitHub使用总结

Tue, 01 Jan 2019 14:13:54 +0800

Git的官方网站：http://git-scm.com

Git和GitHub使用总结

一、GIT初始化设置：

创建密钥

1

ssh‐keygen ‐t rsa ‐C "lingcoder@gmail.com"

远程仓库

1
2
3
4
5
6
7
8


添加远程origin库关联
git remote add origin git@github.com:lingcoder/xxx.git

查看远程仓库
git remote -v

删除远程origin库的关联
git remote rm origin

用户名邮箱配置

全局配置

1
2
3


 git config --global user.name "lingcoder"
 git config --global user.email "lingcoder@gmail.com"
 git config --list

项目单独配置（在项目根目录下）

1
2
3


 git config user.name "lingcoder"
 git config user.email "lingcoder@gmail.com"
 git config --list

设置Git默认分支名为 main

1

 git config --global init.defaultBranch main

创建本地仓库

1

git init

Clone远程仓库

1

git clone 项目地址

格式化与空白

 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



1. 问题来源：
Windows使用回车和换行两个字符来结束一行，而Mac和Linux只使用换行一个字符

2. 换行定义：
CR Carriage-Return的缩写： 回车(CR, ASCII 13, \r)
LF Line-Feed的缩写，换行(LF, ASCII 10, \n) 
window 采用CRLF 
Linux，Mac采用LF

3. 解决办法：
(0) Git配置
Git可以在你提交代码时自动地把行结束符CRLF转换成LF，而在检出代码时把LF转换成CRLF

⑴ 在Windows系统上与其他系统协作开发
 用core.autocrlf来打开此项功能，如果是在Windows系统上，把它设置成true，这样当检出 代码时，LF会被转换成CRLF： 
 $ git config --global core.autocrlf true

⑵ 在Linux或Mac系统上与其他系统协作开发
 Linux或Mac系统使用LF作为行结束符，如果你不想Git在检出代码时进行自动的转换，把core.autocrlf设置成input来告诉Git在提交代码时把CRLF转换成LF，检出时不转换： 
 $ git config –-global core.autocrlf input 
这样在Windows系统上检出的代码会保留CRLF；而在Mac和Linux系统上，以及仓库中保留LF。

⑶ 团队都是在Windows系统上开发
 如果在Windows系统上开发程序，且正在开发仅运行在Windows上的项目，可以设置false取消此功能，把回车符记录在库中： 
 $ git config –-global core.autocrlf false

代理设置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


查看全局代理设置
git config --global http.proxy

设置http,https,socket代理 以`127.0.0.1:1080`为例
git config --global http.proxy 'http://127.0.0.1:1080'
git config --global https.proxy 'http://127.0.0.1:1080'
git config --global http.proxy 'socks5://127.0.0.1:1080'
git config --global https.proxy 'socks5://127.0.0.1:1080'

需要代理用户名密码的情况,以http为例
git config http.proxy http://username:password@127.0.0.1:1080

忽略SSL证书错误
git config --global http.sslVerify false

删除 proxy 
git config --global --unset http.proxy
git config --global --unset https.proxy

自定义操作

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


#让Git显示颜色，会让命令输出看起来更醒目
git config ‐‐global color.ui true

#自定义git命令，以简化"git status"成"git st"为例
git config ‐‐global alias.st status

#自定义日志颜色
git config ‐‐global alias.lg "log ‐‐color ‐‐graph ‐‐pretty=format:'%Cred%h%Creset ‐%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' ‐‐abbrev‐commit"

git lg

更新单个文件

1
2
3
4
5
6


更新本地
git checkout -- "[文件路径]/[文件名]"

更新远程
git fetch
git checkout origin/master -- ""[文件路径]/[文件名]""

二、GIT基本操作

添加到暂存区区

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


表示添加所有内容 
 git add -A
 
表示添加新文件和编辑过的文件不包括删除的文件
 git add . 
 
表示添加编辑或者删除的文件，不包括新添加的文件
 git add -u
 
强制添加一个被.gitignore文件忽略的文件的版本库
git add ‐f [文件名]

提交

1
2
3
4
5
6


普通提交
git commit`


将本次提交的内容合并到上次提交
git commit --amend

删除

1
2


从版本库删除某个文件
git rm [文件名]

版本回退

1
2
3
4
5
6
7
8


撤回到某个版本
git reset --hard [提交ID]

查看过去的提交历史
git log

查看所有的提交历史
git reflog

撤销修改

1
2
3
4
5


让file回到最近一次 "git commit" 或 "git add" 时的状态
git checkout -- [文件名]

可以把暂存区的file修改撤销掉（unstage），重新放回工作区
git reset HEAD [文件名]

三、GIT分支操作

创建分支

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


创建一个dev分支并且切换到dev分支
git checkout ‐b dev

创建dev分支
git branch dev

切换到dev分支
git checkout dev

创建远程origin的dev分支到本地
git checkout ‐b dev origin/dev

查看分支
git branch

分支命名规范： issue-100 bug修复分支 feature-sms sms功能分支

分支合并

1
2
3
4
5


合并dev到当前的分支
git merge dev

合并分支，并且禁用 Fast forward 
git merge ‐‐no‐ff ‐m "merge with no‐ff" dev

Fast forward模式： Git在merge时生成一个新的commit，以便于从分支历史上就可以看出合并分支信息

分支推送

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


将当前master分支推送到远程,并设置关联
git push ‐u origin master

强制推送dev分支到远程
git push origin dev -f

取出远程dev分支
git fetch origin dev
将当前分支内容重置为取出的dev分支
git reset --hard origin dev

分支绑定

1
2
3
4
5


将本地的dev分支和远程的origin的dev分支绑定
git branch ‐‐set‐upstream-to=origin/dev dev

以后就可以直接pull了
git pull

分支删除

1
2
3
4
5
6
7
8


删除dev分支
git branch ‐d dev

强行删除 
git branch ‐D dev

修剪远程分支
git fetch -p

stash功能

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


把当前的工作状态保存下来，以便于后面恢复，包括index区。
git stash

把当前的工作状态保存下来，以便于后面恢复，包括index区。
git stash list

恢复statsh内容，但是不删除statsh
git stash apply

恢复指定的stash
git stash apply stash@{0}

删除stash内容
git stash drop

恢复同时删除stash内容
git stash pop

四、GIT标签操作

本地操作

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


查看分支
git tag

给当前分支打标签
git tag 

给某个提交打标签
git tag [标签名] [提交ID]

创建带有说明的标签，用 -a 指定标签名， -m 指定说明文字
git tag ‐a [标签名] ‐m "第一个正式版本" [提交ID]

查看标签说明
git show [标签名]

删除标签
git tag -d [标签名]

远程操作

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


标签推送
git push origin [标签名]

推送全部尚未推送到远程的本地标签：
git push origin ‐‐tags

删除远程标签
1. 先删除本地标签
	git tag -d [标签名]
2. 再推送远程
	git push origin :refs/tags/[标签名]

五、Github同步原作者代码

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21



1. 查看远程状态
	git remote -v
	
2. 添加原作者的远程仓库到remote
	git remote add upstream 原作者远程仓库地址
	
3. 同步fork
	git fetch upstream
	
4. 切换到本地主分支
	git checkout master
	
5. 把 upstream/master 分支合并到本地 master
	git merge upstream/master
	
6. push到远程仓库
	git push origin master
	
7. 解决冲突
直接编辑冲突文件，然后提交更改重新push即可

六、GIT多人协作的工作模式

 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


1. 首先，试图推送自己的修改
	git push origin branch-name 

2. 如果推送失败，则因为远程分支比你的本地更新，需先试图合并
	git pull 
	
3. 如果合并有冲突，则解决冲突，并在本地提交

4. 没有冲突或者解决掉冲突后，再推送就能成功！
	 git push origin branch-name

如果"git pull"提示“no tracking information”，则先命令绑定关系
git branch --set-upstream branch-name origin/branch-name


# 日常使用顺序
# 去自己的工作分支
$ git checkout work

工作
....

提交工作分支的修改
$ git commit -a

回到主分支
$ git checkout master

获取远程最新的修改，此时不会产生冲突
$ git pull

回到工作分支
$ git checkout work

用rebase合并主干的修改，如果有冲突在此时解决
$ git rebase master

回到主分支
$ git checkout master

合并工作分支的修改，此时不会产生冲突。
$ git merge work

提交到远程主干
$ git push

七、GIT关联Gitee和GitHub

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


1. 删除已有的默认远程库：
	git remote rm origin

2. 关联码云的远程库 
	git remote add [远程库别名] git@gitee.com:xxx/xxx.git

3. 关联GitHub远程库
	git remote add [远程库别名] git@github.com:xxx/xxx.git

4. 查看远程库信息
	git remote ‐v

5. 分别推送到github和gitee

	以别名github为例，推送到GitHub，使用命令：
	git push github master

	以别名gitee为例，推送到码云，使用命令：
	git push gitee master

至此，我们的本地库就可以同时与多个远程库互相同步

八、Github 解决敏感配置文件上传问题

将真正的config文件加入.gitignore，然后推送一个基本的config_example文件

push 结束后，再把 config_example 添加到 .gitignore 中。

经典情景：别人先clone 你的项目，把 config_example 文件 pull 下来后，复制一份再重命名为config，根据自己的环境稍加修改config文件。然后把两文件都添加到.gitignore 中。以后push 则不会再对远程仓库造成影响。

九、.gitignore文件忽略原则

忽略文件的原则

1
2
3


1. 忽略操作系统自动生成的文件，比如缩略图等；
2. 忽略编译生成的中间文件、可执行文件等；
3. 忽略你自己的带有敏感信息的配置文件，比如存放口令的配置文件。

检查文件忽略情况

1

git check‐ignore ‐v [文件名]

十、搭建git私服，以ubuntu为例

基本使用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


1. 安装git：
	sudo apt-get install git
 
2. 创建一个git用户，用来运行git服务：
 sudo adduser git
 
3. 创建证书登录：
 收集员工公钥`id_rsa.pub`文件，导入到`/home/git/.ssh/authorized_keys`文件里，一行一个。
 
4. 初始化Git仓库：
 选定目录作为Git仓库，假定是`/srv/sample.git`，在`/srv`目录下输入命令：
 sudo git init --bare sample.git

5. 把owner改为`git`
 sudo chown -R git:git sample.git
 
6. 禁用shell登录： 编辑`/etc/passwd`文件
	git:x:1001:1001:,,,:/home/git:/bin/bash
	改为：
	git:x:1001:1001:,,,:/home/git:/usr/bin/git-shell
	
7. 克隆远程仓库：
	git clone git@server:/srv/sample.git

十一、利用git管理svn

简单介绍

GIT自带的git svn命令可以用来管理svn项目，对于习惯使用git的人来说，是一个不错的选择。基本上除了检出，提交，更新代码命令有所区别，大部分都是纯git操作

常用命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


 # 检出svn仓库代码
 git svn clone 
 ## 例子1 将dapp-parent项目检出到当前目录，文件夹名称dapp-parent
 git svn clone http://xxx/dapp-parent
 ## 例子2 将dapp-parent项目检出到当前目录，文件夹名称huizhong
 git svn clone http://xxx/dapp-parent huizhong
 
 # 更新svn仓库的代码到本地当前分支
 git svn rebase
 # 提交本地分支的代码到svn仓库
 git svn dcommit
 # 查看git管理的svn仓库信息
 git svn info
 # 提交git分支到svn分支仓库（需要额外配置，并不常用）
 git svn tag

十二、日志提交规范(参考 Angularjs 提交规范)

build: 影响构建系统或外部依赖关系的更改（示例范围：gulp，broccoli，npm）
ci: 更改我们的持续集成文件和脚本（e.g.: Travis，GitLab 等）
docs: 仅文档更改
feat: 一个新功能
fix: 修复错误
perf: 改进性能的代码更改
refactor: 代码更改，既不修复错误也不添加功能
style: 不影响代码含义的变化（空白，格式化，缺少分号等）
test: 添加缺失测试或更正现有测试
chore: 构建过程或辅助工具的变动
release: 版本发布
revert: 特殊情况，当前 commit 用于撤销以前的 commit

示例

1
2
3
4
5


docs(core): Update inject error documentation(#123)
build: update eslint dependencies to v5.32.0 (#47016) 
fix(router): do not call preload method when not necessary (#47007) 
feat(language-service): support fix the component missing member (#46764)
refactor(common): Align PathLocationStrategy constructor(#123)

十三、将误传至Github的敏感资料删除

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


git filter-branch --force --index-filter 'git rm --cached --ignore-unmatch [敏感文件路径]' --prune-empty --tag-name-filter cat -- --all

git push origin [分支名称] --force

rm -rf .git/refs/original/

git reflog expire --expire=now --all

git gc --prune=now

git gc --aggressive --prune=now

扩展使用

管理公钥 Gitosis
管理权限 Gitolite

Spring Boot 项目打包：War 与 Jar 的区别和注意事项

Tue, 30 Oct 2018 17:00:00 +0800

写在前面

新人接触 Spring Boot 时常困惑一个问题——明明同样是 Java Web 项目，为什么有的项目用 mvn package 出来是个 jar，有的项目却出来一个 war，部署方式还截然不同？

答案要从 Spring Boot 的设计哲学说起。Spring Boot 提倡"内嵌容器、可执行 jar"的方式——一个 java -jar app.jar 就跑起来，再也不用 Tomcat 这样的外部容器。但传统的 Java EE 时代，war 包 + 外部容器才是标准玩法。Spring Boot 也兼容这种做法，让老项目能平滑迁移。

这两种打包方式选错了，轻则启动姿势别扭，重则配置失效、监控失灵。本文把它们的区别、坑、和实操要点一次讲清楚。

War 与 Jar 的本质区别

	Jar 包	War 包
用途	通用 Java 库、可执行应用	Java Web 应用归档（Web Application Archive）
入口	`META-INF/MANIFEST.MF` 的 Main-Class	`WEB-INF/web.xml` 或 `ServletContainerInitializer`
部署	`java -jar app.jar`	拷到 Tomcat/Jetty 的 `webapps` 目录
容器	内嵌（Tomcat/Jetty/Undertow）	外部
静态资源	`BOOT-INF/classes/static`	项目根目录或 `webapp` 下
类加载顺序	由 Spring Boot Loader 控制	由外部容器控制

最关键一句话——jar 把容器装进了应用，war 把应用装进了容器。这条决定了两者后续所有差异。

Spring Boot 默认推荐 Jar，原因是什么

Spring Boot 默认 jar 不是凭感觉，是经过权衡的。

Jar 的好处：

零运维：不需要装 Tomcat，不需要管 server.xml，部署=拷贝 jar 包
环境一致：开发、测试、生产用的是同一个内嵌 Tomcat，行为一致
容器版本可控：升级 Tomcat 只是改 pom 依赖
天然适合容器化：一个 jar 就是一个 Docker 镜像的核心
每个应用独立运行：互不影响，Crash 隔离

War 的传统优势在云原生时代逐渐弱化：

原本"一个 Tomcat 跑多个应用"的模式，被 Kubernetes 一个 Pod 一个应用替代了
原本"运维统一管 Tomcat"的优势，被容器编排取代了
原本"war 包小，复用容器"的优势，对几百 MB 起步的 Spring 应用根本不算优势

所以现在的工程默认建议：除非有明确历史包袱或合规要求，新项目一律 jar。

怎么打 Jar 包

Spring Boot 项目默认就是 jar。pom.xml 里：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<packaging>jar</packaging>

<build>
 <plugins>
 <plugin>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-maven-plugin</artifactId>
 </plugin>
 </plugins>
</build>

spring-boot-maven-plugin 的 repackage 目标会把项目打成"可执行 jar"——里面包含一个特殊的 BOOT-INF/lib/ 装所有依赖，外层有 Spring Boot 自己的 JarLauncher：

1
2
3
4
5
6
7
8


app.jar
├── META-INF/
│ └── MANIFEST.MF ← Main-Class: org.springframework.boot.loader.JarLauncher
├── org/springframework/boot/loader/ ← Spring Boot 启动类加载器
└── BOOT-INF/
 ├── classes/ ← 你的代码
 ├── lib/ ← 所有第三方依赖 jar
 └── classpath.idx

启动方式：

1
2


java -jar app.jar
java -Xms512m -Xmx2g -jar app.jar --spring.profiles.active=prod

怎么打 War 包

把同一个项目改成 war 输出，需要四步：

1. 改 packaging

1

<packaging>war</packaging>

2. 排除内嵌 Tomcat

外部容器已经提供了 Servlet 容器，再带一份会冲突：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-web</artifactId>
 <exclusions>
 <exclusion>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-tomcat</artifactId>
 </exclusion>
 </exclusions>
</dependency>

<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-tomcat</artifactId>
 <scope>provided</scope> <!-- 编译用，不打进 war -->
</dependency>

3. 启动类继承 `SpringBootServletInitializer`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


@SpringBootApplication
public class Application extends SpringBootServletInitializer {

 @Override
 protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) {
 return builder.sources(Application.class);
 }

 public static void main(String[] args) {
 SpringApplication.run(Application.class, args);
 }
}

SpringBootServletInitializer 会让 war 既能 java -jar 跑，也能丢进 Tomcat 跑。保留 main 方法是个好习惯——本地调试还是 java -jar 最方便。

4. 部署

把生成的 app.war 拷贝到 $TOMCAT_HOME/webapps/ 下，Tomcat 自动解压并启动：

1

http://host:port/app/... ← context path 默认是 war 包名

七个最常见的 War 部署坑

坑 1：context path 不一致

java -jar 启动时，Spring Boot 默认 context path 是 /；war 部署到 Tomcat 时，context path 默认是 war 文件名。前端写死接口路径的话，部署完所有请求 404。

对策：要么把 war 重命名为 ROOT.war（context path = /），要么前端通过相对路径拼接。

坑 2：内嵌 Tomcat 没排干净

如果忘了 <scope>provided</scope>，war 里会带一份 Tomcat。在外部 Tomcat 里跑会出现 ClassLoader 冲突——NoSuchMethodError、LinkageError 各种奇葩报错。

对策：用 mvn dependency:tree 检查 war 里没有 tomcat-embed-*。

坑 3：`server.port` 配置失效

application.yml 里的 server.port: 8081 在 war 部署里完全无效——端口由外部 Tomcat 决定。同理 server.servlet.context-path 也无效。

对策：明确知道这些"server.*“配置只对内嵌容器生效。

坑 4：`@PropertySource` 找不到外部配置

java -jar 时 Spring Boot 会自动加载 jar 同级目录的 application.yml 覆盖内置；war 部署时没有"jar 同级目录"这个概念，外部配置要显式放在 Tomcat 的 lib 或者通过 -Dspring.config.location= 指定。

对策：

1
2


# 在 Tomcat 启动参数里加
-Dspring.config.location=file:/etc/myapp/application.yml

坑 5：日志文件路径混乱

Spring Boot 的 logging.file.name=app.log 是相对当前工作目录的，war 部署时这个目录是 Tomcat 的 bin/，不是你以为的项目目录。

对策：日志路径永远写绝对路径。

坑 6：JSP 默认不支持

Spring Boot 的可执行 jar 不支持 JSP（这也是为什么老项目改造时会被卡）。war 部署时虽然支持，但前提是：

1
2
3
4
5


<dependency>
 <groupId>org.apache.tomcat.embed</groupId>
 <artifactId>tomcat-embed-jasper</artifactId>
 <scope>provided</scope>
</dependency>

对策：新项目用 Thymeleaf / Freemarker / 前后端分离，远离 JSP。

坑 7：Filter / Listener 触发顺序

外部 Tomcat 加载 war 时，@WebFilter 等注解的扫描机制和 Spring Boot 自带容器有差异。某些 Filter 可能比 Spring 容器还早初始化，导致 @Autowired 是 null。

对策：用 FilterRegistrationBean 显式注册 Filter，由 Spring 控制生命周期。

镜像化时代的最佳实践

如果你的项目要打 Docker 镜像，强烈推荐用 jar：

1
2
3


FROM eclipse-temurin:17-jre
COPY target/app.jar /app.jar
ENTRYPOINT ["java", "-jar", "/app.jar"]

简单、清晰、可复制。war + Tomcat 的镜像虽然也能跑，但要装 Tomcat、改 server.xml、暴露端口，且镜像体积更大、启动更慢。

进一步的优化是用 Spring Boot 的 Layered Jar 把不变的依赖和频繁变化的业务代码分层，加速 Docker 镜像构建：

1
2
3
4
5
6
7
8
9


<plugin>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-maven-plugin</artifactId>
 <configuration>
 <layers>
 <enabled>true</enabled>
 </layers>
 </configuration>
</plugin>

1
2
3
4
5
6


FROM eclipse-temurin:17-jre
WORKDIR /app
COPY target/app.jar app.jar
RUN java -Djarmode=layertools -jar app.jar extract
# Spring Boot 3.2+ 路径
ENTRYPOINT ["java", "org.springframework.boot.loader.launch.JarLauncher"]

版本注意：ENTRYPOINT 类路径在 Boot 3.2 处发生过迁移——Boot 3.2+ 用 org.springframework.boot.loader.launch.JarLauncher，3.1 及以下是 org.springframework.boot.loader.JarLauncher。两者写错都会启动报 ClassNotFoundException，按你实际的 Boot 版本选。

选择决策树

flowchart TD
 Start([新项目还是老项目?])
 Start -->|新项目| Jar1[直接用 Jar]
 Start -->|老项目| Old{有外部 Tomcat 集群?}
 Old -->|没有| Jar2[迁移成 Jar]
 Old -->|有| Reason{为什么用外部 Tomcat?}
 Reason -->|历史习惯| Migrate[评估迁移成本，建议慢慢转 Jar]
 Reason -->|多应用共享容器| Docker[考虑 K8s 替代]
 Reason -->|合规/审计要求| War[继续用 War]
 Reason -->|JSP/老旧依赖| War

小结

War 与 Jar 的选择，本质上是"跟着 Java EE 时代的部署模式走，还是跟着云原生的部署模式走”。

给一句决策建议：

新项目优先用 Jar。老项目能改就改。除非有合规/历史/JSP 强约束，否则没有理由再用 War。

Spring Boot 仍然完整支持 war 是为了向后兼容，不是推荐方向。把这点拎清楚，后面所有选择就都顺了。

Tomcat8日志切割和定期删除

Tue, 17 Oct 2017 09:02:06 +0800

日志切割

安装 cronolog

安装

1
2
3
4
5
6
7


# 下载cronolog-1.6.2.tar.gz 并解压
wget http://cronolog.org/download/cronolog-1.6.2.tar.gz 
# 解压
tar zxvf cronolog-1.6.2.tar.gz
# 编译安装
cd cronolog-1.6.2
./configure && make && make install

验证安装

1
2
3
4


# 验证是否安装成功
which cronolog
# 显示以下信息则成功
# /usr/local/sbin/cronolog

修改 Tomcat 8 配置

替换 tomcat 目录下 /bin/Catalina.sh 文件内容

1
2
3
4
5


 if [ -z "$CATALINA_OUT" ] ; then

 CATALINA_OUT=日志路径/catalina.out

 fi 

为

1
2
3
4
5


 if [ -z "$CATALINA_OUT" ] ; then

 CATALINA_OUT=日志路径/catalina.%Y-%m-%d.out

 fi

注释掉 touch "$CATALINA_OUT"

1

 #touch "$CATALINA_OUT"

替换（共有两处修改）

1
2


 org.apache.catalina.startup.Bootstrap "$@" start \
 >> "$CATALINA_OUT" 2>&1 &

为

1
2


 org.apache.catalina.startup.Bootstrap "$@" start 2>&1 \
 | /usr/local/sbin/cronolog "$CATALINA_OUT" >> /dev/null &

重启 tomcat 即可。

定时删除

新建 xxx.sh 文件，添加内容如下：

1
2
3
4


#!/bin/sh
find /usr/local/apache-tomcat-8.5.15/logs/ -mtime +1 -name "*.out" -exec rm -rf {} \;
find /usr/local/apache-tomcat-8.5.15/logs/ -mtime +1 -name "*.log" -exec rm -rf {} \; 
find /usr/local/apache-tomcat-8.5.15/logs/ -mtime +1 -name "*.txt" -exec rm -rf {} \;

执行 crontab -e 命令打开定时任务配置文件，在里面录入

1

10 0 * * * sh 目录/xxx.sh > /dev/null 2>&1

定时任务cron命令示例：

1
2
3
4


* * * * * # 每隔一分钟执行一次任务 
0 * * * * # 每小时的0点执行一次任务，比如6:00，10:00 
6,10 * 2 * * # 每个月2号，每小时的6分和10分执行一次任务 
*/3,*/5 * * * * # 每隔3分钟或5分钟执行一次任务，比如10:03，10:05，10:06 

工程实践 on 牛哥聊技术

Spring Boot 配置加载机制详解

几乎每个 Spring Boot 项目都遇到过

一、Spring Boot 配置的"位置"全集

二、为什么命令行优先级最高

三、application.yml 在哪些位置会被找到

四、Profile 机制：环境维度切换

激活 Profile

Profile 文件命名

多 Profile 同时激活

spring.profiles.include

五、bootstrap.yml vs application.yml

六、外部化配置：12-Factor 的最佳实践

七、@Value vs @ConfigurationProperties

@Value：单字段注入

@ConfigurationProperties：批量映射

@RefreshScope

八、调试技巧：搞清楚配置从哪里来

1. Actuator 的 /actuator/env

2. 启动日志 DEBUG

3. 启动参数检查

九、几个最常被踩的坑

坑 1：YAML 缩进与冒号后空格

坑 2：Profile 里的相对路径

坑 3：环境变量大小写转换

坑 4：占位符递归

坑 5：@ConfigurationProperties 没生效

十、生产 Checklist

小结

软件研发生命周期中的核心文档梳理

软件研发生命周期中的核心文档梳理

1. 项目启动与可行性分析阶段

1.1 项目建议书/立项文档

1.2 可行性分析报告（可选）

2. 需求分析阶段

2.1 业务需求文档/需求调研报告

2.2 软件需求规格说明书（SRS）

2.3 原型图 / 交互设计文档（可选）

3. 设计阶段

3.1 概要设计说明书（High-Level Design, HLD）

3.2 详细设计说明书（Low-Level Design, LLD）

4. 实现与测试阶段

4.1 测试用例说明书 / 测试计划

4.2 测试报告

5. 上线与运维阶段

5.1 发布手册/上线方案

5.2 用户手册/操作说明

5.3 运维手册/技术支持文档

结语

如何把 Go 模块文档发布到 pkg.go.dev

写在前面

一、pkg.go.dev 是什么

二、最小可发布的 Go 模块

1. 仓库结构

2. go.mod

3. doc.go：包级文档

4. README.md

三、文档规范：让 godoc 漂亮

1. 每个导出符号都要有注释

2. 多行注释

3. 列表

4. 可执行示例

5. 标题（Go 1.19+）

四、版本管理：发布正式版本

1. 用 git tag 发布

2. 让 pkg.go.dev 收录新版本

3. v2+ 的特殊规则

五、license 文件：影响排名

六、CI 集成：自动化发布

七、提高搜索排名

八、常见问题

1. 推了 tag 但 pkg.go.dev 没显示

2. README 里的图片不显示

3. 私有仓库怎么办

4. 删除已发布版本

5. examples 怎么组织

九、一份发布前 Checklist

小结

Conda和poetry搭配使用

Markdown 常见语法整理

`spring.profiles.include`

五、`bootstrap.yml` vs `application.yml`

七、`@Value` vs `@ConfigurationProperties`

`@Value`：单字段注入

`@ConfigurationProperties`：批量映射

`@RefreshScope`

1. Actuator 的 `/actuator/env`

坑 5：`@ConfigurationProperties` 没生效

十二、KaTeX 数学公式（需 `math: true`）