Estrutura de um projeto Java: src, package, classpath

1. Pasta src — onde vive o seu código

Se um projeto Java fosse uma casa, a pasta src seria a sala de estar aconchegante onde se reúnem todos os principais moradores (as suas classes). É justamente aqui que ficam todos os arquivos-fonte com código — não na raiz do projeto, não na pasta de configurações e muito menos na área de trabalho (mesmo que a tentação seja grande).

Por que separar os fontes do restante?

• Na pasta src ficam apenas os arquivos que você escreve manualmente: .java.
• Tudo o que aparece no processo de build (por exemplo, arquivos .class, arquivos temporários) vai para outras pastas (out, build, target etc.).
• Isso facilita a navegação, torna o projeto mais limpo e deixa a IDE mais feliz.

Exemplo de estrutura de um projeto simples:

MyFirstProject/
├── .idea/           # arquivos de serviço da IntelliJ IDEA, não mexa
├── out/             # aqui aparecem os arquivos .class compilados
├── src/             # é aqui que vive o seu código-fonte!
│   └── Main.java
├── MyFirstProject.iml
└── README.md

Importante:
Tudo o que você escreve — classes, pacotes, interfaces — deve estar na pasta src. Não coloque ali imagens, músicas e receitas secretas — para isso existem outras pastas.

2. Pacotes package

Em Java é comum agrupar classes em “pacotes” — como pastas no sistema de arquivos, só que para classes. Os pacotes ajudam a:

• Evitar conflitos de nomes: se houver duas classes Main no projeto, em pacotes diferentes elas não atrapalham uma à outra.
• Estruturar o código logicamente (por exemplo, com.codegym.tasks, com.mycompany.utils).
• Controlar o acesso a classes e métodos.

Sintaxe de declaração de pacote

No início de cada arquivo Java (antes de todos os import e de class) escreve-se a linha:

package com.codegym.lesson05;

Isso significa: a classe deste arquivo pertence ao pacote com.codegym.lesson05.

Importante:
As pastas no sistema de arquivos devem corresponder ao nome do pacote! Se estiver escrito package com.codegym.lesson05;, o caminho para o arquivo será:

src/com/codegym/lesson05/Main.java

Como criar um pacote no IntelliJ IDEA

1. No painel do projeto, clique com o botão direito na pasta src.
2. Escolha New → Package.
3. Digite o nome, por exemplo: com.codegym.lesson05 (a IDE criará as pastas aninhadas automaticamente).
4. Agora crie uma nova classe dentro desse pacote. Clique com o botão direito na pasta com.codegym.lesson05 e escolha New → Java Class. E digite o nome

Exemplo:

src/
└── com/
    └── codegym/
        └── lesson05/
            └── User.java

Por que não é uma boa ideia simplesmente colocar tudo em src?

Se você colocar todas as classes misturadas, o projeto rapidamente vira um “lixão”, em que achar o arquivo certo será mais difícil do que encontrar o carregador do notebook em um alojamento estudantil. Use pacotes — assim fica mais fácil escalar o projeto, integrar bibliotecas de terceiros e dividir o código entre diferentes equipes.

3. Nome completo da classe

Toda classe em Java está obrigatoriamente em algum pacote. Pacote é apenas uma “pasta” dentro da biblioteca de classes. Por exemplo:

• A classe System fica no pacote java.lang. Seu nome completo é java.lang.System.
• A classe Scanner fica no pacote java.util. Seu nome completo é java.util.Scanner.
• A classe ArrayList também está em java.util, portanto seu nome completo é java.util.ArrayList.

Ou seja, nome completo da classe = nome do pacote + ponto + nome da classe.

Vamos usar isso no código:

java.util.Scanner sc = new java.util.Scanner(System.in);
String name = sc.nextLine();
System.out.println("Olá, " + name);

Aqui escrevemos explicitamente java.util.Scanner. O compilador entende de qual classe estamos falando, mesmo que haja outras classes com o nome Scanner no programa.

Isso é muito importante: o nome da classe pode coincidir, mas o nome completo é sempre único.

Por que precisamos do nome completo?

Imagine que temos duas classes diferentes Date:

• java.util.Date (classe antiga para trabalhar com datas),
• java.sql.Date (data para trabalhar com bancos de dados).

Se você simplesmente escrever:

Date d = new Date();

O compilador não saberá qual Date você quer usar. Mas se você escrever o nome completo:

java.util.Date d1 = new java.util.Date();
java.sql.Date d2 = new java.sql.Date(System.currentTimeMillis());

— não haverá confusão.

4. Operador import

Escrever o nome completo da classe toda hora é incômodo. É para isso que existe o operador import em Java.

Se escrevemos:

import java.util.Scanner;

Isso significa: “Neste programa, vou usar a classe Scanner do pacote java.util”. Depois disso podemos escrever apenas:

Scanner sc = new Scanner(System.in);

e o compilador entenderá que se trata de java.util.Scanner.

Import comum (uma classe)

Este é o caso mais comum. Indicamos uma classe específica:

import java.util.Scanner;
import java.util.ArrayList;

Agora podemos escrever nomes curtos: Scanner, ArrayList.

Importar o pacote inteiro *

Às vezes o programa usa muitas classes de um mesmo pacote. Nesse caso, pode-se escrever:

import java.util.*;

Isso significa: “Permitir usar todas as classes do pacote java.util sem o nome completo”.

Agora é possível escrever:

Scanner sc = new Scanner(System.in);
ArrayList<String> list = new ArrayList<>();

Mas é importante lembrar: import java.util.*; importa apenas as classes do pacote java.util, mas não dos subpacotes. Por exemplo, a classe java.util.concurrent.ConcurrentHashMap não será incluída. Ela precisa ser importada separadamente.

O que não é possível fazer com import

• import não pode ser usado dentro de um método — ele é escrito apenas no início do arquivo.
• import não carrega classes na memória. Ele apenas diz ao compilador de onde obter a classe.
• import não substitui o nome completo quando há duas classes iguais.

5. Classpath — como o Java encontra suas classes

Classpath é a “rota” pela qual o Java procura suas classes ao executar o programa. Pense nisso como uma lista de pastas onde o Java buscará os arquivos .class necessários (as versões compiladas dos seus .java).

Por padrão, a IDE adiciona automaticamente a pasta src (ou a pasta de classes compiladas, por exemplo, out/production/ProjectName) ao classpath. Ou seja, se você escreveu uma classe no pacote com.codegym.lesson05, o Java irá procurá-la no caminho:

out/production/ProjectName/com/javarush/lesson05/Main.class

Como o classpath funciona no IntelliJ IDEA?

• Quando você executa o programa pela IDE, ela define automaticamente o classpath necessário.
• Se você executa o programa pela linha de comando, precisa indicar explicitamente o classpath com a flag -cp ou -classpath.
• Todas as classes do seu projeto e das bibliotecas conectadas devem estar em pastas que estejam no classpath.

6. Organização do código no projeto

Uma classe — um arquivo

Em Java, é prática que cada classe public fique em um arquivo separado, com o mesmo nome da própria classe. Por exemplo, se a sua classe é Person, o arquivo deve se chamar Person.java.

Exemplo:

src/com/javarush/lesson05/Person.java

package com.codegym.lesson05;

public class Person {
    String name;
}

Os nomes dos arquivos e das classes devem coincidir

Se a classe se chama MySuperClass, então o arquivo deve ser MySuperClass.java. Isso não é capricho, é uma exigência do compilador Java. Se você errar, receberá um erro na etapa de compilação.

Onde armazenar recursos (imagens, arquivos de texto)?

• Para recursos costuma-se criar uma pasta separada, por exemplo, resources ou res.
• No IntelliJ IDEA, você pode adicionar essa pasta com o clique direito na pasta: Mark Directory as → Resources Root.
• O código Java pode acessar esses arquivos via classpath.

Exemplo de estrutura:

MyFirstProject/
├── src/
│   └── com/javarush/lesson05/
│       └── Main.java
├── resources/
│   └── config.txt

8. Erros típicos ao trabalhar com a estrutura do projeto

Incompatibilidade entre a estrutura de pastas e o pacote
Se no início do arquivo estiver package com.codegym.lesson05;, mas o arquivo estiver em src/Main.java, o compilador gerará o erro "package does not exist" ou "class not found". Sempre verifique se as pastas correspondem ao nome do pacote!

Incompatibilidade entre o nome do arquivo e o da classe
Se a classe se chama Person, mas o arquivo é People.java, você receberá "class Person is public, should be declared in a file named Person.java".

Mover arquivos manualmente sem atualizar o pacote
Se você moveu o arquivo para outra pasta, mas esqueceu de alterar a linha package, o programa não será compilado. Faça isso na janela Project da IDE — ela atualizará o package automaticamente!

Recursos não adicionados ao classpath
Se você armazena arquivos (por exemplo, de texto) fora da pasta resources e não marcou a pasta como Resources Root, o programa não conseguirá encontrá-los via classpath.