优雅开源框架中的类名与函数名命名前后缀总结

优雅开源框架中的类名与函数名命名前后缀总结

主流开源框架的命名并非随意，而是围绕职责可读性、设计模式、生命周期、约定俗成形成的体系。本文按类名、函数名、跨语言习惯分类整理，便于在设计与评审时快速查阅。

---

一、类名 / 类型名常见前后缀

1. 设计模式与结构角色

前后缀	含义	典型示例
Abstract*	抽象基类，定义骨架	Spring AbstractApplicationContext
Base*	可复用基类	Django BaseCommand
Default*	默认实现	Netty DefaultChannelPipeline
*Impl / *Implementation	接口的具体实现	Java ArrayList 常配套 List 接口
*Builder	构建器模式	OkHttp Request.Builder
*Factory	工厂创建对象	Spring BeanFactory
*Adapter	适配器，桥接不同接口	Android ArrayAdapter
*Wrapper / *Delegate	包装/委托，增强或代理	Guava ForwardingList
*Proxy	动态代理	JDK Proxy
*Strategy	策略模式（有时显式命名）	各类 *CompressionStrategy
*Template	模板方法模式	Spring JdbcTemplate

2. 职责与分层

前后缀	含义	典型示例
*Service	业务逻辑层	Spring @Service
*Repository / *Dao	数据访问层	Spring Data UserRepository
*Controller / *Handler	请求入口/处理	Spring MVC UserController
*Manager	资源或状态管理	Android FragmentManager
*Provider	提供某类能力/数据	Spring Security AuthenticationProvider
*Resolver	解析/裁决	Spring HandlerMethodArgumentResolver
*Registry	注册中心/注册表	Spring BeanDefinitionRegistry
*Store / *Cache	存储/缓存	Redux createStore
*Context	运行时上下文	Spring ApplicationContext
*Config / *Configuration / *Properties	配置相关	Spring Boot *AutoConfiguration
*Module	功能模块单元	NestJS UserModule
*Component	可组合单元	React MyComponent

3. 横切关注点

前后缀	含义	典型示例
*Filter	过滤链中的一环	Servlet Filter
*Interceptor	拦截器	MyBatis Interceptor
*Middleware	中间件	Express/Koa middleware
*Aspect	切面	Spring AOP
*Listener / *Observer	事件监听	Java ActionListener
*Subscriber / *Publisher	发布订阅	RxJava
*Validator	校验器	Hibernate Validator
*Converter / *Mapper / *Transformer	类型/结构转换	MapStruct UserMapper
*Serializer / *Deserializer	序列化	Jackson JsonSerializer
*Encoder / *Decoder	编解码	Netty codec

4. 网络与 I/O

前后缀	含义	典型示例
*Client / *Server	客户端/服务端	gRPC *Stub / *Service
*Connection / *Session	连接/会话	JDBC Connection
*Channel / *Pipeline	通道/处理链	Netty
*Protocol	协议定义	HTTP/2
*Request / *Response	请求/响应模型	几乎所有 Web 框架

5. 异常、工具、常量

前后缀	含义	典型示例
*Exception / *Error	异常类型	IllegalArgumentException
*Utils / *Helper / *Kit	无状态工具类	Apache StringUtils
*Constants	常量集合	HttpStatusConstants

6. 接口命名习惯（语言差异）

习惯	语言/生态	示例
I* 前缀	C#、部分老 Java/C++	IEnumerable
无 I 前缀，*able 形容词接口	Java 现代风格	Runnable, Serializable
动词或名词，靠语义区分	Go、Rust	io.Reader, Iterator trait

---

二、函数 / 方法名常见前后缀

1. 访问器（JavaBean / 通用约定）

前缀	含义	示例
get*	获取属性	getName()
set*	设置属性	setTimeout()
is* / has* / can*	布尔判断	isEmpty(), hasNext(), canRead()
should*	条件性判断（偏策略）	shouldRetry()

2. 生命周期

前缀	含义	示例
init* / setup* / configure*	初始化	init(), configure()
start* / stop* / pause* / resume*	启停控制	startServer()
destroy* / dispose* / close* / shutdown* / cleanup*	释放资源	close(), shutdown()
reset*	重置状态	reset()
refresh* / reload*	刷新/重载	refreshContext()

3. 数据操作（CRUD 与查询）

前缀	含义	示例
create* / new* / make* / build*	创建对象	createConnection(), build()
find* / query* / fetch* / load* / read*	查询读取	findById(), load()
save* / store* / persist* / insert* / update*	写入更新	save(), persist()
delete* / remove* / drop* / clear*	删除清理	removeListener()
add* / put* / append*	添加元素	addEventListener()
count* / size* / length*	计数	count()

4. 转换与解析

前缀	含义	示例
parse*	字符串/数据 → 对象	parseInt(), parseQuery()
format*	对象 → 字符串	formatDate()
to*	类型转换	toString(), toJSON()
from*	静态工厂式构造	fromString(), Value.from()
serialize* / deserialize*	序列化	serialize()
encode* / decode*	编解码	encodeURIComponent()
convert* / transform* / map*	结构转换	mapToDTO()

5. 处理与执行

前缀	含义	示例
handle* / process* / execute* / run* / invoke* / apply*	执行核心逻辑	handleRequest(), run()
dispatch* / emit* / trigger* / fire*	分发/触发事件	emit('click')
on*	事件回调	onClick(), onMessage()
do*	模板方法中的钩子	Spring doFilter()
try*	尝试执行（可能失败）	tryLock(), tryParse()

6. 校验与断言

前缀	含义	示例
validate* / check* / verify*	校验	validateInput()
assert*	断言（测试/调试）	assertNotNull()
ensure* / require*	前置条件保证	requireNonNull()

7. 注册与订阅

前缀	含义	示例
register* / unregister*	注册/注销	registerBean()
subscribe* / unsubscribe* / publish*	发布订阅	subscribe()
bind* / unbind*	绑定关系	bindEvents()
attach* / detach*	挂载/卸载	attachShader()

8. 流式 API（Builder / Fluent）

前缀	含义	示例
with*	链式设置	withTimeout(30)
and* / or*	组合条件	Query DSL 中常见
then*	异步链式	Promise .then()

9. 框架扩展点（Spring 等典型）

前后缀	含义	示例
*PostProcessor	后置处理器	BeanPostProcessor
*Aware	注入某能力	ApplicationContextAware
*Registrar	注册扩展	ImportBeanDefinitionRegistrar
*Customizer	定制默认行为	WebMvcConfigurer
*Condition	条件装配	OnClassCondition

---

三、各生态特有约定

Java / Spring 生态

• 类 ：*AutoConfiguration, *Properties, *Template, *Holder
• 方法 ：after*, before*（生命周期钩子），supports*（能力探测）

JavaScript / TypeScript / React

• 类/组件 ：*Provider, *Context, *Hook（自定义 hook 常以 use 开头）
• 函数 ：use*（Hook），create*（工厂，如 createContext），with*（HOC）

Go

• 接口 ：常以 -er 结尾 → Reader, Writer, Handler
• 函数 ：New* 构造，Must* 失败即 panic，Is* / Has* 判断

Rust

• Trait ：动词或 *able → Iterator, Clone, Debug
• 函数 ：new, with_*, into_*, as_*, try_*, from_*

Python / Django / Flask

• 类 ：*Mixin（混入），*View, *Form, *Serializer
• 函数 ：get_*_or_*, *_url, *_path（Django 路由辅助）

Ruby on Rails

• 类 ：*Controller, *Mailer, *Job, *Policy
• 方法 ：scope :*, before_*, after_*, *_path, *_url

---

四、优雅命名的核心原则

1. 名即文档 ：看到 *Builder、*Handler、*Repository 应能猜出职责，无需翻源码。
2. 前后缀表达角色，中间词表达领域 ：如 UserAuthenticationFilter = 用户 + 认证 + 过滤器。
3. 动词表动作，名词表事物 ：parseJson() 做解析，JsonParser 是解析器类。
4. 对称命名 ：register / unregister，subscribe / unsubscribe，open / close。
5. 避免空洞词 ：少用 Manager、Helper、Util 当万能后缀；能具体就具体（ConnectionPool 优于 ConnectionManager）。
6. 与语言惯例一致 ：Go 用 NewX，Rust 用 from/into，Java 用 get/set，不强行混用。
7. 框架扩展点要可发现 ：Spring 的 *Aware、React 的 use* 形成生态内「看到就懂」的词汇表。

---

五、速查对照（最常用 Top 20）

类名后缀

Builder, Factory, Handler, Service, Repository, Config, Context, Adapter, Wrapper, Listener, Provider, Filter, Interceptor, Converter, Exception, Client, Controller, Impl, Template, Utils

函数前缀

get/set, is/has/can, create/build, find/load, parse/format, validate/check, handle/process, init/close, register/subscribe, on/to/from, with, try, start/stop

---

六、命名组合示例

以下示例展示「领域词 + 角色后缀」的常见组合方式：

场景	推荐命名	说明
用户认证拦截	UserAuthenticationInterceptor	领域 + 职责
订单查询服务	OrderQueryService	读写分离时可区分 Query/Command
JSON 解析工具	JsonParser / parseJson()	类用名词，函数用动词
数据库连接池	ConnectionPool	具体优于 ConnectionManager
配置自动装配	RedisAutoConfiguration	Spring Boot 惯例
事件监听器	OrderCreatedEventListener	事件名 + Listener
请求参数解析	PageableArgumentResolver	Spring MVC 扩展点
链式构建	HttpClient.newBuilder().connectTimeout(...).build()	Builder 模式

---

七、反模式（尽量避免）

反模式	问题	更好做法
DataManager / CommonHelper	职责模糊	UserRepository, DateFormatter
processData()	不知道处理什么	validateOrder(), enrichUserProfile()
doSomething()	无业务语义	用动词 + 领域对象
Utils 类无限膨胀	上帝工具类	按领域拆分 StringUtils, JsonUtils
混用多种语言风格	可读性差	遵循当前语言/框架惯例
IUserService + UserServiceImpl	Java 现代项目已较少使用	直接 UserService 接口 + DefaultUserService

---

文档版本：v1.0 | 适用于架构设计、代码评审、框架扩展开发参考