1. Java类定义的基本结构
包与导入
在Java中，包声明和导入语句是类文件的前置声明，包名和导入路径决定了类的命名空间与可访问的类型。包声明通常位于文件开头，紧跟在任何注释之后，以确保编译器能正确解析相对路径和引用。
如果使用 公共类，通常文件名必须与该类的 公开类名 相同。违反该规则会导致编译错误，因此在设计 API 时要留意命名约束。
package com.example.api;
import java.util.List;
import java.util.Map; // 引入需要的类型
// 该文件名应为 UserApi.java，如果存在公开类 UserApi
类声明的基本语法
类的声明包括 访问修饰符、可选的 abstract、final 修饰符，类名、以及可选的 extends 与 implements。
一个最简单的类定义示例展示了如何组织字段和方法的基本结构，便于阅读与维护，同时为后续扩展留出空间。
public class User {
// 成员变量放在这里，完成对象的状态描述
}
字段声明与初始化
字段的类型决定了对象的状态，私有字段有助于实现封装，静态字段属于类级别而非实例级别，常用于统计或常量。
初始化可以通过直接赋值、构造方法或初始化块来完成。请注意字段的初始化顺序与静态块的执行顺序，避免出现未初始化的引用。
public class User {
private static int count = 0;
private String name;
public User(String name) {
this.name = name;
count++;
}
}
2. 成员变量与方法的声明规则
访问修饰符与默认可见性
Java 提供 public、protected、private 和 package-private（无修饰符）四种访问级别。合理的可见性是实现良好封装的关键。
将字段设为 private，并提供公共的 getter/setter，是实现封装的常见做法。下面的示例展示了基本做法，并强调对外暴露 API 的控制。
public class Person {
private String name;
int age; // 同包可见
public String getName() { return name; }
public void setName(String name) { this.name = name; }
}
方法声明、重载与返回值
方法需要明确的返回类型、名称和参数列表。方法重载通过不同的参数签名来实现。返回类型与方法签名分离，重载只看参数列表而非返回值。
如果方法没有返回值，应使用 void，并注意对异常的处理。下面的示例展示了重载与基本语义。
public class Calculator {
public int add(int a, int b) { return a + b; }
public double add(double a, double b) { return a + b; }
public void reset() { /* no return */ }
}
3. 构造方法、初始化块与对象创建
构造方法的规则与最佳实践
构造方法名必须与类名相同，且没有返回类型。构造方法用于初始化对象的状态，若未显式定义，编译器会提供默认构造方法。
使用构造方法时，通常会对必选字段进行赋值，防止出现不完整对象。注意不要在构造方法中执行耗时的 I/O 操作，避免影响对象的初始化完整性。
public class User {
private final String name;
private int age;
public User(String name) {
this.name = name;
this.age = 0;
}
}
初始化块、static 块与对象创建顺序
初始化块用于在构造方法执行前执行统一的初始化逻辑，静态初始化块在类加载阶段执行一次。理解它们的执行顺序对避免初始化时序问题很重要。
在对象创建时，遵循静态字段初始化 → 实例字段初始化 → 构造方法的顺序，确保对象初始状态的一致性。
public class Example {
private static int global;
private int value;
static {
global = 100;
}
{
value = 10;
}
public Example() {
// 构造时执行
}
}
super() 与 this()
子类通过 extends 实现继承，子类构造方法必须显式或隐式调用 super() 来初始化父类部分。this() 可以在同一个构造器内调用另一构造器，以避免重复代码。
class Animal {
protected String name;
Animal(String name) { this.name = name; }
}
class Dog extends Animal {
private int age;
Dog(String name, int age) {
super(name);
this.age = age;
}
}
4. 继承、接口、以及多态相关的语法要点
继承与接口实现
类通过 extends 关键字实现单继承，implements 实现一个或多个接口。接口定义方法签名，默认是 public abstract；从 Java 8 起可有默认方法。
多态依赖于对父类型的引用指向子类型实例，通过动态绑定实现运行时行为的多态性。合理使用多态可以提升代码的可扩展性与可维护性。
interface Vehicle {
void drive();
}
class Car implements Vehicle {
public void drive() { System.out.println("Driving"); }
}
抽象类、接口与默认方法
抽象类可以包含未实现的方法，接口在 Java 8 及以上支持默认方法实现。抽象类不能直接实例化，但可通过子类实例化。
注意在接口中定义的字段默认是 public static final 常量，且方法默认为 public 抽象方法，除非使用 default 关键字实现。
abstract class Shape {
abstract double area();
}
interface Drawable {
void draw();
default void colorize() { /* default implementation */ }
}
5. 常见坑、规范写法与编码规范
命名与文件结构的常见坑
Java 对命名有明确的规范：类名使用 CamelCase，方法与字段使用 lowerCamelCase。公开类必须与文件名同名，否则编译器会抛出错误。
避免在一个文件中定义多个公共类，保持单一职责，提高代码的可维护性与可测试性。
// 文件名：UserService.java
public class UserService {
// 实现细节
}
封装、不可变对象与对外API设计
推荐将字段设为 private，并通过公开的 getter/setter 进行访问。若对象应不可变，可将字段设为 final，并仅通过构造器设值，从而确保对象的一致性和可预测性。
对对外 API，优先使用接口类型引用实现，降低耦合，提升测试性和可替换性。
public interface Repository {
void save(Data d);
Data load(String id);
}
代码风格与注释
遵循团队的代码风格、统一的缩进、空格与换行，以及对公共 API 的 Javadoc 注释，提升代码可读性与可维护性。
注释应准确描述行为，避免冗余信息。下面是一个简单的 Javadoc 示例，用于说明类的用途和字段。
/**
* Represents a user in the system.
*/
public class User {
private String id;
private String name;
public String getName() { return name; }
}
