企业官网建设流程全解析

1. 项目拆解：文档基础注意点到底在注意什么

1.1 从一次夜班编译失败说起

我印象很深的一次经历，是在一个快上线的晚上，同事发来一段很简单的Java代码，逻辑一眼就能看懂，结果一编译直接报illegal character。排查了半天，最后发现罪魁祸首是一个全角分号。那段代码是从某个文档网站上复制下来的，网页排版把半角分号悄悄换成了全角分号，编译器看到这个字符，直接判定为“非法字符”。整行代码明明长得一模一样，就是跑不过去。

类似的情况还有几种：javadoc注释里多写了一个@，或者把/**写成了/*；方法参数列表里中文逗号和英文逗号混着用；{@code}内联标签里面少了一边花括号，导致生成文档时整段注释解析失败。这些问题的本质，全部可以归到同一个主题：Java文档基础注意点，以及分隔符（也就是代码里的标点符号）的正确使用。

这也是我今天想把“java文档基础注意点(分隔符即标点符号的代码用例)”这个主题拆开讲清楚的原因。不是讲什么高深架构，而是把那些最基础、最容易被忽略、又最容易在面试和加班时坑人的细节，用代码用例过一遍。

1.2 这篇内容适合谁、学完能拿什么

如果你是刚学Java的同学，或者写了两三年代码但很少去翻《Java语言规范》的开发者，又或者正在准备java面试、想看java基础八股文里关于标识符、分隔符、注释规则的部分，这篇内容能帮你省不少翻文档和踩坑的时间。

读完你至少能拿到三样东西：

• 对Java七种标准分隔符有一个系统认识，知道它们在源码和文档中分别扮演什么角色；
• 掌握 javadoc 文档注释的书写规范，包括@param、@return、{@code}这些标签怎么用才不出错；
• 拿到一个基于 Unicode 类别判断中英文标点符号的完整代码用例，可以直接拷进项目里当工具类用。

2. Java里的分隔符：它们凭什么被单独列为一类？

2.1 七个标准分隔符逐个拆解

如果你看过 Java Language Specification（JLS）的词法结构，会发现编译器把源码里的字符分成了几类：标识符、关键字、字面量、运算符、分隔符。其中分隔符这一组，就是{}、[]、()、;、,、.、...这七种。

它们看着像“标点符号”，但在编译器眼里，它们是有明确语法职责的边界符号，少一个、多一个、写错一个，轻则编译失败，重则生成完全不是预期的业务逻辑。逐个说一下：

花括号{}

• 类体和方法体的边界。一个类里从{开始到}结束，编译器才知道哪里是class的管辖范围。
• 静态初始化块、实例初始化块、代码块，也需要{}。
• “空块”也是一个合法语句，比如{}本身。

方括号[]

• 数组的直接标志。int[] arr声明一个整型数组。
• 访问数组元素时同样离不开它：arr[0]。
• 多维数组就是多组方括号叠加，int[][] matrix。

圆括号()

• 方法声明和调用的参数列表元字符：public void test(String name)。
• 控制语句的条件部分也靠它：if (x > 0)、while (running)。
• 表达式里改变运算优先级时，圆括号也是标准工具。

分号;

• 语句结束符。Java 里几乎每条语句都要以;结尾。
• for 循环头的三个表达式之间也是用分号隔离的：for (int i = 0; i < 10; i++)。

逗号,

• 分隔方法参数、多个变量声明、数组初始化的元素列表。
• 声明多个同类型变量时可以连写，例如int a = 1, b = 2;。
• 在for循环初始化或更新部分写多个表达式，也需要逗号。

点.

• 成员访问运算符。System.out.println这个链条里，两个点分别把System、out、println串起来。
• 也用于包名层级，如com.example.demo。

省略号...

• JLS 把它定义为分隔符，表示可变参数。
• 写法：public void printAll(String... args)，在方法内部使用args时它就是一个String[]数组。

很多教材把.和...归类到运算符里，这其实不准确。JLS 分隔符章节里明确列出了它们。面试时如果被问“Java有哪些分隔符”，你按七种来答，通常会被认为更贴合官方表述。

2.2 分隔符语法细节与易混点

这七种分隔符看着简单，实际使用时却有几个高频混淆点。

第一，分号只出现在语句末尾，不写会编译报错，但写完也别乱加。有人会写出if (a == 1);这种“光杆分号”，此时if的条件体变成了一个空语句，后续代码块跟if完全无关。这种bug特别隐蔽，因为代码看起来没有任何语法错误，实际执行逻辑却完全变了。这是java基础面试题里很喜欢考的“空语句”陷阱。

第二，圆括号和方括号的使用位置不能换。方法声明用的是圆括号，数组声明用的是方括号。String args()和String[] args是完全不同的东西。早期学习时我一直记混过main方法的声明，写成了public static void main(String args[])，后来才意识到规范推荐把方括号放在类型旁边：public static void main(String[] args)。

第三，中文逗号和中文分号在代码级别跟英文的并不是“等价替换”。这一点极其重要。很多中文输入法在切换状态时会把标点自动改成全角，导致代码里出现全角括号、全角分号、全角逗号。Java编译器对这类字符的态度是“不识别”。全角分号；不是语句结束符；全角逗号，不是参数分隔符；全角括号（）不是分组或者参数列表的一部分。这也是为什么我在开头强调，区分中英文标点这件事，不止是文本排版问题，直接关系到代码能不能编译。

2.3 一个综合代码用例，把所有分隔符串起来

下面这个类演示了七种分隔符的常见组合用法，每行都有注释标出对应分隔符：

package com.example.separator; // . 包层级分隔 import java.util.Arrays; public class SeparatorDemo { // {} 类体边界 public static void main(String[] args) { // () 参数列表，{} 方法体边界 int[] nums = {1, 2, 3, 4}; // [] 数组类型与访问，{} 数组初始化列表，, 元素分隔 System.out.println("sum=" + sum(nums)); // . 成员访问，; 语句结束符 String[] words = {"java", "doc", "separator"}; printWords(words); // () 方法调用 printNumbers(10, 20, 30); // ... 可变参数的实际调用方式 } private static int sum(int[] arr) { int total = 0; for (int i = 0; i < arr.length; i++) { // () 控制条件，{} for循环体，; 循环头分隔 total += arr[i]; // [] 访问数组元素 } return total; } private static void printWords(String[] words) { System.out.println(Arrays.toString(words)); } private static void printNumbers(int... numbers) { // ... 可变参数声明 for (int number : numbers) { System.out.println(number); } } }

这个例子不算复杂，但里面每一种分隔符都在工作。把这段代码跑一遍，再把其中任意一个半角符号改成全角符号，你就能立刻体会到什么叫“代码对标点极其敏感”。

3. 文档注释基础注意点：先会写，再谈优雅

3.1 三种注释形式，别把注释种类写错位

Java 的注释分三种，这是文档注释的“基础注意点”里最前置的一条。

• //单行注释：只能注释一行内容，用于临时说明和行尾注。
• /* */块注释：可以跨行，用于大段说明或者临时屏蔽代码块。
• /** */文档注释：可以被 javadoc 工具识别并生成 HTML API 文档。只有这种注释里的内容才会进入<pre>风格的文档页面。

很多人用 javadoc 时最容易犯的第一个错误是：把文档注释写成了/* */。/* 计算两个数之和 */这种写法没问题，但它不会被 javadoc 当作文档内容处理，项目里生成接口文档时会漏掉一大段方法说明。反方向也一样，如果只是想注释一段暂时不用的代码，却用/** */，生成文档时那些临时代码文本就会被收录进去，污染 API 文档。

还有一个很常见的细节：文档注释的星号数量必须严格是两个。/**是文档注释的入口，/*是块注释的入口，/***有三个星号也不会报错，但 javadoc 会把第一个星号之后的全部内容当作普通文档文本，反而可能产生多余字符。

3.2 javadoc 标准标签怎么组织才规范

文档注释的内容有约定俗成的排版顺序。

最上面是一个摘要句，也就是方法的简短说明，通常要求用一句话说清楚方法“做了什么”。摘要句之后可以写详细描述。再往后，是各种块标签，最常见的三个是：

• @param解释方法参数；
• @return描述返回值；
• @throws说明可能抛出的异常。

写的时候有几个容易出错的点必须提一下。

第一，块标签必须独占一行，标签名不能写错。@param后面先跟参数名，再跟描述文字。如果参数名写错，javadoc 会提示@param name找不到对应的形参。@return则不要写“return”，也不要写@返回值，javadoc只认识官方约定的英文标签。

第二，摘要句不能以标点结尾，而且要简洁。这是非常容易被忽略的规范。javadoc第一句话会被提取成方法列表里的摘要文本，如果摘要句以句号结尾，生成文档时摘要可能会截断地比较难看，和描述部分区分不清晰。所以通常第一句不带句号，写到说明性内容再另起段落。

第三，文档注释里写 HTML 标签时，需要注意前后闭合。javadoc生成的页面本质是 HTML，所以你可以在注释里使用<p>、<ul>、<li>、{@code}等元素。但要保证标签成对出现，不要写<ul>却忘了</ul>。否则文档页面渲染时会出问题，有的开发环境直接解析失败。

一个可以参考的方法说明模板：

/** * 计算两个整数相加的结果。 * * <p>本方法提供最基础的加法运算，直接使用 {@code +} 运算符实现。</p> * * <ul> * <li>入参为 int 类型；</li> * <li>结果越界时不会自动报错，请调用方自行校验；</li> * <li>更安全的加法可以看 {@link Math#addExact(int, int)}。</li> * </ul> * * @param a 第一个加数 * @param b 第二个加数 * @return 两数之和 * @see Math#addExact(int, int) */ public int add(int a, int b) { return a + b; }

其中{@code +}表示以等宽字体显示一个代码字符+；{@link Math#addExact(int, int)}表示生成一个跳转到Math.addExact方法的链接。这两个标签在 javadoc 里非常常见，它们的共同特征是：都依赖花括号作为内联标签的分隔符。

3.3 花括号在文档注释里的特殊含义

这就是标题里“分隔符即标点符号”最有意思的体现。

Java文档注释里有两种标签：一种是块标签，例如@param、@return，它们独占一行；另一种是内联标签，例如{@code}、{@link}、{@value}，它们要写在{}内。花括号在这里就是内联标签的分隔符，起到界定标签类型和参数范围的作用。

写反了会怎样？曾经我在给一个枚举常量的文档注释写默认值时，写了{@value}，但少打了一个右半边}，整个项目生成 javadoc 时后面一大段内容都变红异常。最麻烦的是编译器本身并不报错，因为注释内容只是文本，javadoc 工具才会去解析。等到 API 文档发布出来，才发现那一节内容全部渲染混乱了。

所以平时写文档注释的时候，要特别盯着{}是否成对。它就像代码里的括号配对一样，要求前后对称。如果你用的 IDE 是 IntelliJ IDEA，写{@code}时会有高亮提示，花括号不匹配时整段注释会变色警告，这是一个值得随时查看的信号。

文档注释里还有一个跟分隔符相关的重灾区：写 HTML 显式标签时用了全角尖括号。比如有人会在文档里写<p>，结果全角状态下写成了＜p＞，javadoc 完全识别不出来。这类问题一般不报编译错误，但生成的 HTML 文档根本达不到预期效果。

4. 实战代码用例：基于 Unicode 类别判断中英文标点符号

4.1 为什么需要一段判断代码

前面讲的都是“写代码时不要把标点写错”，那怎么从程序层面自动识别一个字符到底是不是中英文标点？这个需求在真实项目里其实不少见。

比如解析外部导入的 Excel 文本、清洗爬虫抓回来的页面内容、校验用户输入的账号名是否包含特殊标记符号，或者就是想做一个代码静态检查工具，在 commit 前自动扫一遍源码里有没有全角逗号全角分号。这时候就需要一个工具方法，能判断给定字符是中文字符、英文字符、中文标点，还是英文标点。

很多 Java 开发第一时间想到的是正则表达式，比如[\u3001-\u303F]或者 Unicode 全角区间。但正则写起来容易遗漏，而且面对 JavaScript 风格的标点和中文特有标点时会覆盖不全。更稳的方案是利用java.lang.Character提供的 Unicode 类别（Category）信息，再辅以几个关键码位区间来判定。

这里要区分两个概念：

• Unicode 类别，也就是Character.getType(char)的返回值，可以告诉你这个字符是“起始标点”、“结束标点”、“连接标点”还是“其他标点”。
• 中英文标点判定，光靠 Unicode 类别还不够，因为英文逗号,和中文全角逗号，的类别都可能是OTHER_PUNCTUATION。所以还需要结合码位范围，比如全角字符区间U+FF00 到 U+FFEF，以及中日韩统一表意文字兼容区等范围。

4.2 完整代码用例

下面这个工具类可以放进任何项目，主方法是judge(char)，它会输出字符的 Unicode 码位、Unicode 类别名称，以及最终判定结果。

import java.util.HashSet; import java.util.Set; /** * 中英文标点判断工具。 * * <p>这里的“中文标点”指导常中文排版的标点， * 如，。！？；：“”（）《》等；</p> * * <p>“英文标点”指 ASCII 范围内的半角标点，如 ,.;:!?</p> */ public class PunctuationJudge { /** ASCII 可见字符中属于英文标点的码位区间：0x21 - 0x7E 里的非字母数字字符 */ private static boolean isAsciiPunctuation(int cp) { if (cp < 0x21 || cp > 0x7E) { return false; } if (cp >= 0x30 && cp <= 0x39) { // 0-9 return false; } if (cp >= 0x41 && cp <= 0x5A) { // A-Z return false; } if (cp >= 0x61 && cp <= 0x7A) { // a-z return false; } return true; } /** 常见中文标点的 Unicode 码位区间 */ private static boolean isCjkPunctuation(int cp) { // 、。〃 if ((cp >= 0x3001 && cp <= 0x3003) || cp == 0x3004 || cp == 0x3006 || cp == 0x3007) { return true; } // 《》「」『』【】等等 if (cp >= 0x3008 && cp <= 0x3011) { return true; } // 〔〕〖〗〘〙 等 if (cp >= 0x3014 && cp <= 0x301F) { return true; } // 中文竖排变体标点 if (cp >= 0xFE10 && cp <= 0xFE1F) { return true; } // 全角 ASCII 标点：！＂＃＄％＆＇（）＊＋，－．／：；＜＝＞？＠［＼］＾＿｀｛｜｝～ if (cp >= 0xFF01 && cp <= 0xFF65) { return true; } return cp == 0x2026; // 省略号 } /** 根据 Unicode 类别获取可读名称 */ public static String unicodeTypeName(char ch) { switch (Character.getType(ch)) { case Character.START_PUNCTUATION: return "START_PUNCTUATION(起始标点)"; case Character.END_PUNCTUATION: return "END_PUNCTUATION(结束标点)"; case Character.CONNECTOR_PUNCTUATION: return "CONNECTOR_PUNCTUATION(连接标点)"; case Character.DASH_PUNCTUATION: return "DASH_PUNCTUATION(连接号/破折号)"; case Character.OTHER_PUNCTUATION: return "OTHER_PUNCTUATION(其他标点)"; case Character.INITIAL_QUOTE_PUNCTUATION: return "INITIAL_QUOTE_PUNCTUATION(左引号)"; case Character.FINAL_QUOTE_PUNCTUATION: return "FINAL_QUOTE_PUNCTUATION(右引号)"; default: return "NOT_PUNCTUATION"; } } /** 判断字符是中文标点还是英文标点，或者都不是 */ public static String judge(char ch) { int cp = ch; if (isCjkPunctuation(cp)) { return String.format("字符[%s] U+%04X -> %s -> 中文标点", ch, cp, unicodeTypeName(ch)); } if (isAsciiPunctuation(cp)) { return String.format("字符[%s] U+%04X -> %s -> 英文标点", ch, cp, unicodeTypeName(ch)); } return String.format("字符[%s] U+%04X -> %s -> 非标点", ch, cp, unicodeTypeName(ch)); } public static void main(String[] args) { String samples = "a,.;:，。；：（）《》"; for (char c : samples.toCharArray()) { System.out.println(judge(c)); } } }

这段代码跑出来，大概能看到这样一组结果：

字符[a] U+0061 -> NOT_PUNCTUATION -> 非标点 字符[,] U+002C -> OTHER_PUNCTUATION(其他标点) -> 英文标点 字符[.] U+002E -> OTHER_PUNCTUATION(其他标点) -> 英文标点 字符[，] U+FF0C -> OTHER_PUNCTUATION(其他标点) -> 中文标点 字符[。] U+3002 -> OTHER_PUNCTUATION(其他标点) -> 中文标点 字符[；] U+FF1B -> OTHER_PUNCTUATION(其他标点) -> 中文标点 字符[（] U+FF08 -> START_PUNCTUATION(起始标点) -> 中文标点

4.3 核心逻辑的逐层说明

这段代码虽然不长，但有几个点值得展开讲。

Unicode 类别和“中英文标点”不是一回事。Character.getType(char)是从 Unicode 字符数据库里读出的分类，它只负责“这个字符是什么性质的标点”，不会告诉你这个标点是来自中文排版还是英文排版。所以我要单独把中文标点的码位范围列出来，例如U+3001是顿号，U+3002是句号，U+FF0C是全角逗号。对英文标点，则直接检查 ASCII 可见字符区间0x21-0x7E中非字母数字的部分。

有的人会问：直接用Character.getType(ch) != Character.NOT_PUNCTUATION来判断是不是标点不就行了？对“判断是不是标点”这个问题是可以的，但对“判断是中文还是英文标点”不够。英文的.和中文的。都是OTHER_PUNCTUATION，不看码位区间根本分不出来。

中文标点不只有全角逗号那种情况。常用的中文标点分布在好几个 Unicode 码位区块：一般标点区块的U+3000-0x303F，里面包括顿号、句号、各种括号；全角形式区块的U+FF00-0xFFEF，里面包括全角逗号、全角分号、全角括号；兼容性标点区块的U+FE10-0xFE1F，用于竖排文本。有的标点比如省略号……是两个U+2026字符拼起来的，也需要单独考虑。

可变参数...也是分隔符。文中代码使用了int... numbers，而这个...从 Java 语法角度讲也是标准分隔符。你如果对“分隔符即标点符号”这个题目足够敏感，就会发现这些概念在底层是相通的：代码里的符号、文档注释里的内联标签符号、文本处理里的标点判断，本质上都是“根据符号所在语义位置做边界识别”。

5. 常见问题速查与面试追问实录

5.1 几个高频问题的对照速查表

这部分内容在面试、日常开发和文档编写里都会用到。整理成表格方便速查：

这个速查表不是标准文档里的东西，全是我在实际开发里处理过或者听人求助过的真实问题。前四条尤为高频。

5.2 面试中最容易被追问的细节

java基础面试题里，跟这个主题相关的题几乎必有一两道。最常被问的是下面几种：

• “Java 有哪些分隔符？”答七种，按 JLS 顺序说：{}、[]、()、;、,、.、...。
• “int...和int[]有什么区别？”很多人只知道一个是可变参数一个是数组类型，但更完整的答法是：两者在方法内使用时的类型本质上都是数组，但可变参数是语法层面的糖，调用时可以不显式构造数组，直接把多个值传进去。
• “javadoc 里说@param和{@code}哪种是块标签，哪种是内联标签？”块标签是@param、@return、@throws；内联标签是{@code}、{@link}、{@value}。
• “全角逗号是哪个码位？”全角逗号，的码位是U+FF0C，英文逗号是U+002C。能答出来这一点，面试官一般会认为你确实排查过字符编码问题。
• “怎么用 Java 判断一个字符属于标点？”提到Character.getType(char)的返回值区间，再把中英文标点的码位范围分开处理，就是一道完整的加分答案。

这类题都不难，但信息比较碎。如果只看教材不写代码，很容易被问住。

5.3 避坑心得：我自己吃过的几个教训

这部分是我最想分享的实操经验，因为都不是从文档里看来的，而是踩坑踩出来的。

第一个教训：在项目里加一个“全角字符检查”的静态代码扫描规则。像 Checkstyle、SpotBugs 或者 IDE 自带 Inspections 都可以做到。IntelliJ IDEA 里有一个检查项叫Incorrect formatting of a statement或类似的全角符号检查，直接把全角字符标出来。当年公司有一次交付前代码评审，就是因为一个全角逗号出现在switch的常量值里，导致线上测试失败，后来加了扫描规则，就再没出过同类事故。

第二个教训：写 javadoc 时，把“先写标签骨架，再填描述”养成习惯。很多人写完方法后在注释里随意写，最后的顺序很乱。我的习惯是每次新建一个对外方法，先写出：

/** * 一句话说明。 * * @param * @return * @throws */

先把骨架点出来，让 IDE 自动补全参数名，再往里面填描述。这样既不会漏标签，花括号配对也有 IDE 的语法高亮兜底。

第三个教训：不要轻易复制网页上的代码块，尤其是中文社区文章里的示例。这不是说中文社区不好，而是网页排版常常污染代码字符。复制下来后先看一眼引号、分号、括号是不是半角。我自己的习惯是复制完代码立即按一次Ctrl+Alt+L格式化，大部分可见的全角标点在格式化后立刻会变得显眼，因为代码缩进和空格排布会透露出异常。

第四个教训：很多中英文标点混用的问题发生在文档注释的正文里，而不是代码里。代码里的全角标点编译器会报错，容易发现；文档注释里的全角标点可能只是让文档观感不好，或者影响 HTML 解析，不容易发现。所以写文档时也要保持输入法状态稳定，不要中文输入状态下输入法自动改变引号和括号。如果注释里明确就是中文句子，那用中文全角标点其实是正确的；怕的是同一个段落里中英文标点混用，那才是最难受也最难统一的地方。、。

写在最后

如果你问我这个项目主题里最值得记住的一点是什么，我的答案是：分清楚你当前处于“代码上下文”还是“文档上下文”。在代码上下文里，Java 编译器只认那七种标准分隔符的半角形式，多用全角标点，哪怕肉眼看着一模一样，编译器也会翻脸。在文档上下文里，自然语言文本用中文全角标点是完全合理的，但标签、内联标签和 HTML 元素需要遵守另一套符号规则。

我在实际项目里见过太多人把这两件事搞混了。有人以为“文档注释里写什么都行”，结果把{@code}花括号写丢；也有人以为“所有 Java 标点都要半角”，结果连描述文字里的中文书名号都不敢写。这两种极端都是不对的。

如果你能把今天这套代码用例和数据表存下来，花十分钟跑一遍PunctuationJudge，再把几个常见错误亲手复现一次，你就会对这些基础注意点建立起身体记忆。下次再看到illegal character，你根本不用查资料，心里已经有数了。