docs: update csv student writer contract

This commit is contained in:
2026-08-31 21:57:38 +04:00
parent 62aa619763
commit ac8792eda4
+143 -26
View File
@@ -42,13 +42,13 @@ C25,4.9,10003
---
# `StudentCsvWriter`
## `StudentCsvWriter`
## Назначение
### Назначение
Дозаписывать одного студента в указанный CSV-файл.
Дозаписывать одного студента в **существующий** CSV-файл.
## Контракт
### Контракт
Конструктор:
@@ -65,41 +65,158 @@ public void write(Student student) throws IOException
### Требования
1. Метод принимает одного `Student`.
2. Запись выполняется в режиме добавления.
3. Существующие записи не изменяются.
4. Если файл существует, заголовок повторно не записывается.
5. Если файл не существует, необходимо создать файл.
6. При создании нового файла имя должно соответствовать формату:
2. Указанный файл должен уже существовать.
3. Запись выполняется в режиме добавления.
4. Существующие записи не должны изменяться.
5. Заголовок CSV не должен записываться повторно.
6. Если файл не существует, новый файл **не создавать**.
7. Если файл не существует, метод должен выбросить `IOException`.
8. При успешной записи метод завершается без исключения.
9. Метод не возвращает значение.
10. Исключения, связанные с записью файла, не обрабатывать внутри метода.
11. Исключения `Student` и `StudentBuilder` также не обрабатывать.
## Невозможность записи
Если указанный файл не существует, метод должен выбросить `IOException`.
Также `IOException` должен возникать и передаваться вызывающему коду, если:
- файл недоступен для записи;
- отсутствуют права на запись;
- произошла ошибка файловой системы;
- запись в файл невозможна по другой причине.
Создание файла с именем вида:
```text
students-yyyy-MM-dd-HH-mm.csv
```
Например:
`StudentCsvWriter` **не выполняет**.
```text
students-2026-08-28-20-45.csv
## Пример теста: несуществующий файл
Передать путь к несуществующему файлу:
```java
writer.write(student);
```
1. Новый файл создаётся в директории, указанной абсолютным путём.
2. При создании нового файла сначала записывается заголовок.
3. При успешной записи метод завершается без исключения.
4. Метод не возвращает значение.
5. Исключения, связанные с записью файла, не обрабатывать внутри метода — они должны передаваться вызывающему коду.
6. Исключения `Student` и `StudentBuilder` также не обрабатывать.
Проверить:
## Невозможность записи
```text
IOException
```
Если студент не может быть записан, например:
Проверить также, что новый файл не был создан.
- отсутствуют права на запись;
- невозможно создать файл;
- файл недоступен;
- произошла ошибка файловой системы;
## Изменение теста существующего файла
метод должен выбросить соответствующее исключение, например `IOException`.
Для существующего файла:
Запись не должна возвращать специальное значение вроде `0` для обозначения ошибки.
```text
groupNumber,averageGrade,recordBookNumber
A12,4.5,10001
```
выполнить:
```java
writer.write(student2);
```
Проверить, что результат:
```text
groupNumber,averageGrade,recordBookNumber
A12,4.5,10001
B07,3.8,10002
```
Заголовок присутствует только один раз.
## Дополнительный метод `StudentCsvWriter`
Кроме метода записи одного студента:
```java
public void write(Student student) throws IOException;
```
необходимо реализовать метод:
```java
public void write(MyList<Student>[] students) throws IOException;
```
### Контракт
Метод должен:
1. Принимать массив `MyList<Student>`.
2. Последовательно обрабатывать все переданные коллекции.
3. Записывать каждого студента в указанный CSV-файл.
4. Сохранять порядок:
- коллекций в массиве;
- студентов внутри каждой `MyList`.
5. Использовать тот же формат CSV и те же правила записи, что и `write(Student)`.
6. Работать только с уже существующим файлом.
7. Не создавать файл, если он отсутствует.
8. При отсутствии файла выбрасывать `IOException`.
9. Не изменять переданные `MyList<Student>`.
10. Не обрабатывать исключения, возникающие при создании или валидации `Student`.
11. При ошибке записи прекращать операцию и передавать исключение вызывающему коду.
### Пример
```java
MyList<Student>[] studentLists = ...;
writer.write(studentLists);
```
Если:
```text
studentLists[0] = [Student A, Student B]
studentLists[1] = [Student C]
studentLists[2] = [Student D, Student E]
```
в файл должны последовательно добавиться:
```text
Student A
Student B
Student C
Student D
Student E
```
### Проверка пустых коллекций
Пустые `MyList<Student>` внутри массива не должны приводить к ошибке и не должны добавлять записей в файл.
### Проверка пустого массива
Для:
```java
MyList<Student>[] studentLists = ...; // размер 0
```
метод не должен добавлять никаких записей и не должен изменять файл.
### Проверка отсутствующего файла
Для несуществующего файла:
```java
writer.write(studentLists);
```
должен выбрасываться `IOException`. Файл создавать запрещено.
---